Cursor Builds 与 environment.json 各管哪一层

很多人把 Builds 当成「又一种 environment.json」。其实一层是声明，一层是声明跑完之后留下的可启动快照。混在一起，就会出现：JSON 改对了但 Agent 仍用旧依赖，或以为开了 Builds 就可以删掉仓库里的 JSON。

作者：CodePass 技术编辑

一句话边界

.cursor/environment.json（或 Dashboard 保存的环境）回答：仓库、base（Dockerfile/snapshot）、install / start / terminals、网络与密钥引用。
Builds 回答：按这份声明，在后台已经 clone、装完、snapshot 好的那台机器，Agent 默认从哪一份 Success 启动。

文档原话大意：Builds 仍然使用你已有的 snapshot、Dockerfile、install/startup、secrets 与网络设置；它们不是替代关系。站内已有一篇专讲字段与解析顺序的 environment.json 怎么配，本文只补「和 Builds 叠在一起时谁听谁的」。

谁在什么时候执行命令

层	时机	典型内容
Build + install	后台 Build	依赖安装、生成、编译、暖缓存
Agent + start / terminals	每次 Agent 开跑	Docker daemon、DB、dev server、tmux 里的业务进程

Builds 只固化磁盘。shell 环境变量、内存缓存、当时还在跑的进程，快照时都会停。所以「开了 Builds」之后，更要把 install 写干净：能提前做的都提前做；必须新鲜启动的留给 start。

密钥：Build 期与 Agent 期不是同一把

Build 阶段能用 team / environment secrets（私有 npm、制品库等）。
User secrets 只在 Agent 启动时加入，不会进共享 Build 快照。
因此：把只存在于个人密钥里的 registry token 指望进 install，Build 必红；红了却不影响 active 时，你会误以为「密钥配好了」。保存环境配置或改密钥会触发新 Build——改完盯那一轮日志。

Git：Build 记下的 commit，和你点的分支

Build 记录各仓库当时 checkout 的 commit。

• 默认分支任务：从 active Build 记录的 commit 起。若打开 Update stale builds，且 Build 超过 Staleness threshold（默认 24h，设 0 则总是 pull），Agent 启动时会再拉默认分支最新代码。
• 功能分支任务：先用 Build 准备好的磁盘（依赖已暖），再 checkout 你选的分支。源码跟分支走，依赖尽量复用 Build。
• 分支若改了依赖，Agent 仍拿得到环境上下文与 install 命令，可在开跑前刷新。

多 repo 环境一次 Build 准备全套，并分别记录 SHA。这和「JSON 里声明了哪些仓库」是绑定的：JSON/Dashboard 没挂上的 repo，不会进这份 Build。

setup agent 会动你的 JSON

存量环境点 Run setup agent 时，若环境由 .cursor/environment.json 定义，它可能开 PR 调整 install/start 拆分。Dashboard 托管环境则直接提配置变更供你保存。无论哪条路，启用 Builds 仍是你的显式操作；测配置用 Test build。

8 月 17 日全量默认 Builds 之后，JSON 写错的代价从「每次会话慢」变成「Recurring Build 周期性红、Agent 长期停在旧 Success」。先分清两层，再改文件，比先盲开开关省事。云端怎么用整体入口可看 Cursor in-cloud 怎么用。