cursor environment.json 怎么配 解析顺序与分工

讲清 .cursor/environment.json 的解析顺序、install 幂等与 start/terminals 分工，附可复制示例与 Build 失败恢复要点。

cursor environment.json 怎么配 解析顺序与分工

cursor environment.json 怎么配，取决于你想让 Cursor 在 Ubuntu VM 里复现哪一层开发环境。官方把配置写进仓库的 .cursor/environment.json，Build 在后台装好依赖，Agent 再从 active Build 启动；配错一层，常见症状是 install 卡死、服务起不来，或新 Build 失败却还在用旧镜像。

作者：CodePass 技术编辑

environment.json 管的是 Build，不是聊天窗口

云端 Agent 跑在隔离 Ubuntu 机器上。环境配置要回答四件事：克隆哪些仓库、装什么依赖、注入哪些密钥、启动哪些长驻进程。Dashboard 引导 setup 通常不到 10 分钟：连 GitHub/GitLab/Azure DevOps/Bitbucket、填 Secrets、Agent 在共享终端里装依赖并验证，成功后 Cursor 会 snapshot 环境，并建议把结果 commit 到 .cursor/environment.json 供团队复用。cloud-in-agents-window changelog 对这条路径的描述与文档一致。

Cloud Environment Setup 文档 把这条链路拆成 Build 与 Agent run 两阶段：Build 在后台跑完 install，捕获磁盘状态；Agent 真正开工时再从 active Build 引导，并执行 start 与 terminals。因此 JSON 里的字段对应的是「机器准备好什么」，不是 Composer 里某条提示词。若你关心环境配好以后合并率为何能抬升，可对照 Cloud Agent 环境与 PR 过半 那篇对 anydev 与 Cloud Doctor 的拆解；本文只讲 JSON 文件本身怎么写。

三套配置谁先谁后

Cursor 按仓库或 repo group 解析环境，命中第一条即停。顺序固定如下：

  1. 仓库内的 .cursor/environment.json
  2. 个人 saved environment（Dashboard 里保存的个人配置）
  3. 团队 saved environment

这意味着：仓库里一旦提交了 JSON，团队默认环境和个人覆盖都不会再生效，除非删掉或移走仓库文件。个人环境适合在 rollout 前私测新 install 脚本；团队环境适合给没有 JSON 的旧仓库兜底。多 repo 环境在 Dashboard 选多个仓库时，Cursor 会把各 repo clone 到同一台 Agent 机器，后续 Automations 与 Cloud Agent 共用同一套 Build。

install 必须幂等，且只写磁盘

install 字段是 Build 阶段执行的 shell 脚本。Cursor 每次创建 Build 都会跑它，且可能在已有磁盘状态上重复执行，所以官方明确要求 idempotent（幂等）：多跑一遍结果与跑一遍相同，不能假设「永远是干净机器」。

Build 流程是：从环境 base image 出发 → clone 仓库 → 跑完 install → 成功则 snapshot 为 active Build → 新 Agent 从 active Build 启动。install 适合 pnpm install、代码生成、编译产物、预热缓存等「写完磁盘、下次还能用」的工作。Build 只保留磁盘状态：shell 里 export 的变量、内存缓存、正在跑的进程都不会带进 Agent run，所以别把 dev server 写进 install。

若 Build 失败，不会替换当前 active Build。Agent 仍从最近一次成功的环境启动；你到 Dashboard 的 Builds tab 看日志、从失败 Build 调试，或切回旧的成功 Build。这条恢复规则很重要：改 JSON 可以先在分支上 push，再对该分支开 Agent，Cursor 会在 active Build 之上 checkout 分支，依赖变更时可 rerun install。

install、start、terminals 各放什么

Agent 从 Build 引导完成后，Cursor 先跑 start，再跑 terminals 里配置的命令。二者面向长驻进程，与 install 的分工如下：

字段 执行时机 典型内容 不要放什么
install 每次 Build，后台完成 包管理器安装、代码生成、编译 Docker daemon、数据库、dev server
start Agent 启动时一次 sudo service docker start 等环境级服务 业务应用进程
terminals Agent 启动后，tmux 会话 pnpm dev、API 服务 一次性安装脚本

官方示例：许多仓库可以省略 start；只有依赖 Docker 时才在 start 里起 daemon。terminals 里的进程与你在本地 IDE 终端里留着的窗口等价，Agent 和你共用同一会话。把数据库或前端 dev server 塞进 install，Build 可能 hang 或把半启动状态写进 snapshot，是新手最高频的踩坑。

可直接复制的 environment.json 示例

路径固定为仓库根下 .cursor/environment.json。build.dockerfile 与 build.context 相对 .cursor 解析；install 命令的工作目录是项目根。官方文档示例（含 Dockerfile 与自定义脚本）如下，可直接改文件名与包管理器：

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && ./custom_script.sh",
  "start": "sudo service docker start",
  "terminals": [
    { "name": "web", "command": "pnpm dev" }
  ]
}

若走 Dashboard snapshot 而不是手写 Dockerfile，也可以用 snapshot ID：

{
  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",
  "install": "npm install"
}

snapshot ID 在 Cloud Agents Dashboard 的环境页复制。Dockerfile 路径注意：不要在 Dockerfile 里 COPY 整个项目；Cursor 自己 checkout 工作区到正确 commit。系统级依赖、编译器版本、调试器放 Dockerfile；私有 npm 源等 build-time 凭证用 build secrets，不要写进镜像层。

Secrets 与 AGENTS.md 怎么配合

运行时密钥走 Dashboard 的 Secrets tab（含 environment-scoped secrets），注入为环境变量。登录账号、TOTP secret、AWS IAM role（CURSOR_AWS_ASSUME_IAM_ROLE_ARN）等都在文档里有专门段落；不要把 .env 或 token 硬编码进 Dockerfile 或 JSON。

Cloud Agent 会读 AGENTS.md。官方建议在仓库里加 Cursor Cloud specific instructions 小节，写仅云端需要的 setup、测哪条黄金路径、哪些服务只在特定任务里要起。若说明变长，可拆到其它文件并在 AGENTS.md 里引用，避免把 JSON 撑成说明书。JSON 负责「机器能跑」；AGENTS.md 负责「跑起来后 Agent 该按什么顺序验证」。

参考资料