Cursor Composer：真正好用的多文件编辑

大多数 Cursor 用户只停留在普通聊天。他们问 AI 要个函数，复制输出，贴进文件，重复。小改动没问题。但当你需要改五个文件来实现一个功能时，这个 workflow 就崩了。

Composer 就是 Cursor 给的答案。它是一个独立面板，你描述想改什么，Cursor 就会一次性提出跨多个文件的编辑方案。你审查，逐个接受或拒绝，然后继续。不用复制粘贴，不用来回切换。

这篇指南讲的是 Cursor 论坛里真实有效的工作流。没有营销话术，只有实打实好用的方法。

Composer panel overview

Composer vs 普通聊天：真正的区别

普通聊天是问答。你问，Cursor 答。代码还是要你自己搬进文件。

Composer 是行动。你描述目标，Cursor figuring out 要动哪些文件、改什么。它展示 diff，你决定哪些落地。

功能	普通聊天	Composer
建议代码	有	有
直接编辑文件	否	是
多文件改动	否	是
应用前显示 diff	否	是
检查点/回滚	否	是
最适合	提问、单段代码	重构、功能开发、批量更新

最关键的功能是检查点。Composer 在改动前会保存快照。如果编辑搞砸了，一键就能回滚。普通聊天没有安全网。

怎么打开 Composer

按 Cmd/Ctrl + I 或点击左侧边栏的 Composer 图标。它是独立于聊天的面板——别把两者搞混了。

什么时候用 Composer

Composer 在任务涉及多个文件时发光。常见场景：

重构——跨组件重命名 prop、提取共享工具函数
功能开发——加一个新 API 端点需要改 route、controller、service 和测试文件
模式更新——把 fetch 全部换成自定义的 apiClient
类型改动——更新一个接口，波及十个文件
导入清理——重组模块结构

如果你从聊天里复制代码贴进超过两个文件，停。改用 Composer。

Composer 不是万能的

快速提问、一行代码、或者"解释这个正则"——普通聊天更快。Composer 有 overhead，留给多文件工作。

真实工作流 1：跨文件重构

你的 types.ts 里有个 User 类型。你想把 name 重命名为 fullName，因为你要加 displayName 字段，现在的命名有点混乱。

这会波及：

src/types.ts —— 类型定义
src/components/UserCard.tsx —— 显示名字
src/components/UserProfile.tsx —— 也显示名字
src/api/users.ts —— 收发这个字段的 API 调用
src/lib/validators.ts —— Zod 的用户验证 schema

第一步： 打开 Composer（Cmd/Ctrl + I）。

第二步： 描述改动：

把 User 类型里的 `name` 字段重命名为 `fullName`，并更新代码库里所有用到的地方。不要改任何行为——这是纯重命名。

第三步： 审查提出的 diff。Composer 会高亮显示每个文件的改动。检查：

只有和用户相关的 name 被重命名（不是其他组件的 name prop）
API 层仍然收发正确的数据
没有逻辑改动混进来

第四步： 逐个文件接受或拒绝。如果某个文件看起来不对，只拒绝那一个，手动修复。

仔细审查 diff

Composer 有时候会"手伸太长"。如果上下文看起来类似，它可能会把无关组件里的 name prop 也重命名了。接受前务必扫一眼 diff。

真实工作流 2：跨多个文件添加功能

你想给应用加"用户角色"。管理员能看到额外的 UI 元素，能访问额外的 API 端点。

涉及文件：

src/types.ts —— 给 User 加 role: 'user' | 'admin'
src/api/auth.ts —— 在 JWT payload 里包含 role
src/components/Navbar.tsx —— 管理员才显示 admin 链接
src/components/AdminPanel.tsx —— 新组件
src/hooks/useAuth.ts —— 暴露 isAdmin 标志
src/middleware/auth.ts —— 新中间件检查 admin 角色

第一步： 打开 Composer。

第二步： 给它一个计划，而不是单纯许愿：

给应用添加用户角色：

在 src/types.ts 的 User 类型里加 `role: 'user' | 'admin'`
更新 src/api/auth.ts 的登录响应，在 JWT payload 里包含 role
在 src/hooks/useAuth.ts 里加 `isAdmin` 计算值
更新 Navbar.tsx，isAdmin 为 true 时条件显示 "Admin" 链接
创建 src/components/AdminPanel.tsx，放一个占位用的管理员仪表盘
创建 src/middleware/auth.ts，写 requireAdmin 中间件检查 JWT role

用代码库里现有的模式。遵循其他 API 文件同样的错误处理风格。

第三步： Composer 生成多文件 diff。逐个审查。

第四步： 如果新的 AdminPanel.tsx 看起来不对，拒绝它，保留其他的。Composer 的编辑是细粒度的。

先让它给计划

在让 Composer 写代码之前，先让它 outline 计划。加上一句"在编辑之前列出你会改的文件和原因"。这样能及早发现误解，而且不花什么成本。

真实工作流 3：批量更新 API 调用

你前端里散落着一堆原始的 fetch 调用。现在你有自定义的 apiClient 了，带了认证头、错误处理和 base URL 配置。需要全部迁移。

文件：可能有几十个 API 调用点。

第一步： 先确保 apiClient 已经存在，并且在一个文件里正确导入了。Composer 有参考实现的时候工作得更好。

第二步： 打开 Composer，限定任务范围：

把 src/ 里所有原始的 `fetch` 调用替换成 src/lib/apiClient.ts 里的 `apiClient`。

规则：
- 用现有的 `apiClient.get`、`.post`、`.put`、`.delete` 方法
- 去掉手动的 JSON.stringify 和 response.json() 处理——apiClient 已经做了
- 保持相同的端点路径
- 保留 apiClient 里没有的自定义 header

先从 src/api/ 目录开始，需要的话再处理 src/hooks/。

第三步： 分批审查。别一下子接受 20 个文件不看的。Composer 不错，但不是完美的。

第四步： 接受之后跑测试套件。即使 diff 看起来干净，类型错误和运行时行为也可能有偏差。

别一次性迁移所有东西

如果有 50+ 文件，拆成几块。"先迁移 src/api/"。然后"再迁移 src/hooks/"。大批次难审查，也容易出错。

Composer + Agent 模式：强力组合

Composer 和 Agent 模式解决不同的问题。Composer 适合你知道要做什么的定向多文件编辑。Agent 模式适合开放式任务，AI 需要探索、运行命令、自己 figuring things out。

但它们可以配合。

模式：Agent 规划，Composer 执行

用 Agent 模式搞清楚改动的范围：

我想把 React Context 迁移到 Zustand 做状态管理。列出所有用了 AuthContext 的文件，以及每个文件需要什么改动。

Agent 模式会搜索代码库，给你 breakdown。然后你打开 Composer，逐文件执行改动，有完整的 diff 审查。

模式：Composer 重构，Agent 验证

一次大型 Composer 重构之后，切换到 Agent 模式：

跑测试套件，修复最近重构导致的任何损坏导入或类型错误。

Agent 模式处理清理工作，你 meanwhile 审查 Composer 的改动。

Agent 模式可以用 Composer

在 Agent 模式下，Cursor 有时候会内部打开 Composer 来做多文件编辑。你控制不了这个，但你会在 Agent 会话期间看到 Composer 风格的 diff。同样要审查。

常见错误以及如何避免

1. 提示词太模糊

不好的："把认证弄好一点。"

好的："给 User 类型加 role 字段，更新登录 API 把它放进 JWT，管理员用户在 Navbar 里显示 admin 链接。"

具体能减少意外。

2. 不看就接受

Composer 的 diff 看起来干净，但它可能会：

删掉你想保留的注释
改了无关行的格式
漏掉某个文件的边界情况

永远扫一眼 diff。30 秒的事，能省掉返工。

3. 一次搞太多文件

Composer 处理 10-15 个文件没问题。超过这个数，上下文窗口吃紧，质量下降。把大任务拆成逻辑块。

4. 不用检查点

开始大型 Composer 会话之前，点一下检查点按钮。就点一下。如果会话搞砸了，回滚也是点一下。没理由跳过这个。

检查点不是 Git 提交

Composer 检查点存在 Cursor 内部。它们不能替代 git。大型 Composer 工作之前也要 commit 到 git。两个安全网都用上。

5. 忽略改动后的类型错误

Composer 的编辑大概 90% 能直接编译通过。剩下 10% 会引入微妙的类型不匹配，尤其是重命名或改接口的时候。接受改动后跑一下 tsc 或 linter。

快速参考

动作	快捷键
打开 Composer	`Cmd/Ctrl + I`
接受改动	`Cmd/Ctrl + Y`
拒绝改动	`Cmd/Ctrl + N`
创建检查点	点击 Composer 面板里的检查点图标
回滚到检查点	点击检查点旁边的回滚图标

总结

多文件编辑用 Composer，提问用普通聊天。
描述要具体。包含文件路径和约束条件。
接受前审查每个 diff。
大型会话前创建检查点。
大任务拆成小块。
Composer 配合 Agent 模式：Agent 探索，Composer 执行。

Composer 不是魔法。它是一个工具，消除了多文件工作里的复制粘贴成本。用对了，省几个小时。用草率了，创造清理工作。差别就在审查那一步——别跳过。

Composer vs 普通聊天：真正的区别​

什么时候用 Composer​

真实工作流 1：跨文件重构​

真实工作流 2：跨多个文件添加功能​

真实工作流 3：批量更新 API 调用​

Composer + Agent 模式：强力组合​

模式：Agent 规划，Composer 执行​

模式：Composer 重构，Agent 验证​

常见错误以及如何避免​

1. 提示词太模糊​

2. 不看就接受​

3. 一次搞太多文件​

4. 不用检查点​

5. 忽略改动后的类型错误​

快速参考​

总结​