Cloudflare Computer ignore 模式详解：4 条匹配规则快速判断哪些路径不参与同步
【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer
Cloudflare Computer 是运行在 Durable Object 之上的虚拟文件系统，其 ignore 模式决定了哪些路径段不进入同步协议、不会跨线路传输。本文讲透 ignore 的匹配规则、默认值与覆盖逻辑，帮你为工作区省下数十万个文件级别的同步开销 🚀
为什么需要 ignore：一次 npm install 的代价
在 Cloudflare Computer 中，容器的文件变更会通过 RPC 同步线（sync wire）推送回 Durable Object（下称 DO）。问题在于：node_modules、.next、target这类派生文件目录体积大、文件碎、变化频繁。
官方设计文档指出：没有 ignore，一次npm install就会在下次 pull 时把数万个碎文件推过同步线。这正是 ignore 模式存在的意义——它把这些"用得上但不值得同步"的路径从同步流量中剔除。详见 02_sync_protocol.md。
ignore 匹配规则：整段匹配、路径任意位置生效
核心实现只有 24 行，位于 ignore.ts，判断逻辑是一个isIgnored(path, patterns)函数。规则可以归纳为 4 条：
规则 1：整段匹配，不是子串
路径按/拆分成段，模式必须是完整的一段才命中：
node_modules✅ 命中node_modulesnode_modules❌ 不命中node_modules_old、my_node_modules
规则 2：路径任意位置生效
只要路径中任何一段匹配，整条路径即被忽略，无论嵌套多深：
/a/b/node_modules、/packages/x/node_modules/y/index.js全部命中/a/.next/cache、/rust/target/debug/foo同样命中
规则 3：纯字符串，不支持通配符
当前实现不是 glob，就是逐段精确比较（源码注释明确预留了"有真实需求再扩展 glob"）。所以别指望写*.log——直接写具体目录名更可靠。
规则 4：空列表 = 完全不忽略
模式列表为空时isIgnored恒返回false，即忽略机制被禁用。
以上行为都有对应的测试用例覆盖，可参考 ignore.test.ts 查看每个断言。
默认值与覆盖规则：注意是"替换"而非"追加"
这是最容易踩坑的一点 ⚠️：
| 场景 | 生效的 ignore 列表 |
|---|---|
| 完全没传 ignore | 服务端回退到默认["node_modules"] |
传了自定义列表（如[".next", "dist"]） | 整体替换默认值，node_modules不再被忽略 |
传[] | 彻底禁用忽略 |
服务端回退逻辑见 server.ts：优先用请求里的ignore，否则用实例配置，最后才落到 DEFAULT_IGNORE。
💡最佳实践：自定义列表时把"node_modules"显式带上，例如["node_modules", ".next", "dist", "__pycache__"]。
被忽略的路径会怎样：两侧可见性完全不同
被忽略的路径并非被删除，它在两侧的行为截然不同：
| 维度 | 容器侧 | DO 侧（Workspace.fsAPI） |
|---|---|---|
| 文件是否真实存在 | ✅ 存在 | 对 API 不可见 |
exec/ 构建工具能否使用 | ✅ 照常使用 | — |
readdir | 正常列出 | 不出现 |
stat/readFile | 正常 | 返回ENOENT |
| 是否跨同步线传输 | ❌ 不传输 | — |
也就是说，容器里exec("node ...")、构建工具照样能用node_modules，只是这些字节永远不会上线路，DO 端也看不到它们。SQLite 里甚至没有专门的ignored列——忽略路径对存储层完全透明，见 03_filesystem_schema.md。
ignore 在同步链路中作用于哪里
忽略发生在变更聚合阶段：coalesceChanges在把变更条目送上线路之前，对"存活变更"和"删除墓碑"两个扫描路径都调用isIgnored做过滤（见 coalesce.ts）。这意味着：
- 忽略路径的写入不会成为同步条目；
- 忽略路径的删除同样不会下发——对拉取方来说这些路径始终"不存在"，避免墓碑条目污染接收端。
拉取侧入口fetchChanges也接受同样的ignore选项（fetch.ts）。
工作区级与挂载级 ignore 的叠加
除了顶层工作区配置，每个 mount 还可以单独传ignore（默认[]），与顶层列表按并集叠加：工作区级 ignore 对所有挂载和顶层路径生效，挂载级 ignore 只对当前挂载扩展。完整选项表见 06_mount_interface.md。
常用 ignore 速查清单 📋
针对不同技术栈，推荐的路径段组合（均为整段匹配）：
| 技术栈 | 建议忽略的路径段 |
|---|---|
| Node.js / 前端 | node_modules、.next、dist、build |
| Python | __pycache__、.venv |
| Rust / Go | target、vendor |
| 通用缓存 | .cache、.pytest_cache |
总结
- ignore 用整段精确匹配判断路径是否参与同步，支持路径任意位置、不支持通配符；
- 默认忽略
node_modules，自定义列表是替换而非追加，传[]可禁用； - 被忽略的路径容器侧照常可用，但对
Workspace.fsAPI 完全不可见，也不产生任何同步条目； - 配置点有两层：工作区
ignore+ 每个 mount 的ignore（并集叠加）。
想进一步了解同步协议的完整设计，推荐阅读 docs/ 目录下的规格文档，尤其是 02_sync_protocol.md 的 "Ignore lists" 章节。
【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
