跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

管理文件

最后更新 查看 MarkdownAgent 设置

本指南向您介绍如何在沙箱文件系统中读取、写入、组织和同步文件。

路径约定

文件操作同时支持绝对路径和相对路径：

  • /workspace - 应用程序文件的默认工作目录
  • /tmp - 临时文件（可能会被清除）
  • /home - 用户家目录
// 绝对路径
await sandbox.writeFile("/workspace/app.js", code);

// 相对路径（会话感知）
const session = await sandbox.createSession();
await session.exec("cd /workspace/my-project");
await session.writeFile("app.js", code); // 写入到 /workspace/my-project/app.js
await session.writeFile("src/index.js", code); // 写入到 /workspace/my-project/src/index.js
// 绝对路径
await sandbox.writeFile('/workspace/app.js', code);

// 相对路径（会话感知）
const session = await sandbox.createSession();
await session.exec('cd /workspace/my-project');
await session.writeFile('app.js', code);  // 写入到 /workspace/my-project/app.js
await session.writeFile('src/index.js', code);  // 写入到 /workspace/my-project/src/index.js

写入文件

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// 写入文本文件
await sandbox.writeFile(
	"/workspace/app.js",
	`console.log('Hello from sandbox!');`,
);

// 写入 JSON
const config = { name: "my-app", version: "1.0.0" };
await sandbox.writeFile(
	"/workspace/config.json",
	JSON.stringify(config, null, 2),
);

// 写入二进制文件 (base64)
const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
await sandbox.writeFile("/workspace/image.png", base64, { encoding: "base64" });
import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// 写入文本文件
await sandbox.writeFile('/workspace/app.js', `console.log('Hello from sandbox!');`);

// 写入 JSON
const config = { name: 'my-app', version: '1.0.0' };
await sandbox.writeFile('/workspace/config.json', JSON.stringify(config, null, 2));

// 写入二进制文件 (base64)
const buffer = await fetch(imageUrl).then(r => r.arrayBuffer());
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
await sandbox.writeFile('/workspace/image.png', base64, { encoding: 'base64' });

读取文件

// 读取文本文件
const file = await sandbox.readFile("/workspace/app.js");
console.log(file.content);

// 读取并解析 JSON
const configFile = await sandbox.readFile("/workspace/config.json");
const config = JSON.parse(configFile.content);

// 读取二进制文件（v0.10.1 配合 rpc 传输）
const imageFile = await sandbox.readFile("/workspace/image.png", {
	encoding: "none",
});
return new Response(imageFile.content, {
	headers: { "Content-Type": imageFile.mimeType },
});
// 读取文本文件
const file = await sandbox.readFile('/workspace/app.js');
console.log(file.content);

// 读取并解析 JSON
const configFile = await sandbox.readFile('/workspace/config.json');
const config = JSON.parse(configFile.content);

// 读取二进制文件（v0.10.1 配合 rpc 传输）
const imageFile = await sandbox.readFile('/workspace/image.png', { encoding: 'none' });
return new Response(imageFile.content, {
  headers: { 'Content-Type': imageFile.mimeType }
});

组织文件

// 创建目录
await sandbox.mkdir("/workspace/src", { recursive: true });
await sandbox.mkdir("/workspace/tests", { recursive: true });

// 重命名文件
await sandbox.renameFile("/workspace/draft.txt", "/workspace/final.txt");

// 移动文件
await sandbox.moveFile("/tmp/download.txt", "/workspace/data.txt");

// 删除文件
await sandbox.deleteFile("/workspace/temp.txt");
// 创建目录
await sandbox.mkdir('/workspace/src', { recursive: true });
await sandbox.mkdir('/workspace/tests', { recursive: true });

// 重命名文件
await sandbox.renameFile('/workspace/draft.txt', '/workspace/final.txt');

// 移动文件
await sandbox.moveFile('/tmp/download.txt', '/workspace/data.txt');

// 删除文件
await sandbox.deleteFile('/workspace/temp.txt');

批量操作

并行写入多个文件：

const files = {
	"/workspace/src/app.js": 'console.log("app");',
	"/workspace/src/utils.js": 'console.log("utils");',
	"/workspace/README.md": "# My Project",
};

await Promise.all(
	Object.entries(files).map(([path, content]) =>
		sandbox.writeFile(path, content),
	),
);
const files = {
  '/workspace/src/app.js': 'console.log("app");',
  '/workspace/src/utils.js': 'console.log("utils");',
  '/workspace/README.md': '# My Project'
};

await Promise.all(
  Object.entries(files).map(([path, content]) =>
    sandbox.writeFile(path, content)
  )
);

检查文件是否存在

const result = await sandbox.exists("/workspace/config.json");
if (!result.exists) {
	// 创建默认配置
	await sandbox.writeFile("/workspace/config.json", "{}");
}

// 检查目录
const dirResult = await sandbox.exists("/workspace/data");
if (!dirResult.exists) {
	await sandbox.mkdir("/workspace/data");
}

// 也可在会话中调用
const sessionResult = await session.exists("/workspace/temp.txt");
const result = await sandbox.exists('/workspace/config.json');
if (!result.exists) {
  // 创建默认配置
  await sandbox.writeFile('/workspace/config.json', '{}');
}

// 检查目录
const dirResult = await sandbox.exists('/workspace/data');
if (!dirResult.exists) {
  await sandbox.mkdir('/workspace/data');
}

// 也可在会话中调用
const sessionResult = await session.exists('/workspace/temp.txt');

最佳实践

  • 使用 /workspace - 应用程序文件的默认工作目录
  • 使用绝对路径 - 始终使用完整路径，如 /workspace/file.txt
  • 批量操作 - 对多个独立的文件写入使用 Promise.all()
  • 创建父目录 - 创建嵌套路径时使用 recursive: true
  • 处理错误 - 优雅地检查 FILE_NOT_FOUND 错误

故障排除

目录不存在

请先创建父目录：

// 创建目录，然后写入文件
await sandbox.mkdir("/workspace/data", { recursive: true });
await sandbox.writeFile("/workspace/data/file.txt", content);
// 创建目录，然后写入文件
await sandbox.mkdir('/workspace/data', { recursive: true });
await sandbox.writeFile('/workspace/data/file.txt', content);

二进制文件编码

对二进制文件使用 encoding: "none"（配合 rpc 传输）：

// 写入二进制
await sandbox.writeFile("/workspace/image.png", readableStream);

// 读取二进制
const file = await sandbox.readFile("/workspace/image.png", {
	encoding: "none",
});
// 写入二进制
await sandbox.writeFile('/workspace/image.png', readableStream);

// 读取二进制
const file = await sandbox.readFile('/workspace/image.png', {
  encoding: 'none'
});

关于旧版 SDK 或 http 传输：

// 写入二进制
await sandbox.writeFile("/workspace/image.png", base64data, {
	encoding: "base64",
});

// 读取二进制
const file = await sandbox.readFile("/workspace/image.png", {
	encoding: "base64",
});
// 写入二进制
await sandbox.writeFile('/workspace/image.png', base64data, { encoding: "base64" });

// 读取二进制
const file = await sandbox.readFile('/workspace/image.png', {
  encoding: 'base64'
});

Base64 校验错误

使用 encoding: 'base64' 写入时，内容必须仅包含有效的 base64 字符：

try {
	// 无效：包含无效的 base64 字符
	await sandbox.writeFile("/workspace/data.bin", "invalid!@#$", {
		encoding: "base64",
	});
} catch (error) {
	if (error.code === "VALIDATION_FAILED") {
		// 内容包含无效的 base64 字符
		console.error("Invalid base64 content");
	}
}
try {
  // 无效：包含无效的 base64 字符
  await sandbox.writeFile('/workspace/data.bin', 'invalid!@#$', {
    encoding: 'base64'
  });
} catch (error) {
  if (error.code === 'VALIDATION_FAILED') {
    // 内容包含无效的 base64 字符
    console.error('Invalid base64 content');
  }
}

相关资源

这篇文档对您有帮助吗？