避坑指南与持续成长 · Cursor 橙皮书

一、坑 1：账单爆炸

1.1 怎么发生

某个晚上你让 Agent 跑一个"重构整个项目"的大任务。你跑去吃饭。回来一看 Agent 已经跑了 2 小时，对话历史滚了几屏，用量栏写着 $47。

或者，你装了一个 MCP，AI 在你不知道的情况下反复调用某个 API，月底账单 $200。

1.2 为什么会爆

没看用量：左下角的"用量"图标几天不看一眼。
任务太大：一句话让 AI 改 100 个文件。
模型选错：明明小问题用了 claude-opus（最贵）。
MCP 失控：定时任务 / Cloud Agent 一直在跑。
Max Mode 忘关：开了 Max Mode 后忘记切回普通模式。

1.3 解药

解药 1：每天看一次用量

Cursor 左下角"≡"或"齿轮"图标 → "Usage"。
看本月已用、剩余、预估到月底。
第一周每天看，养成习惯。

解药 2：设置预算告警

Cursor 设置 → Billing → Spending limits。
设一个月度上限（比如 $40）。
超过自动停止 API 调用。

解药 3：模型省着用

简单任务用 composer-2 或 deepseek-v3（便宜）。
复杂任务才用 claude-opus / gpt-5.4-medium。
大批量任务前先用便宜模型验证流程。

解药 4：拆任务

不要让 AI"重构整个项目"——拆成"重构这个文件"、"重构那个文件"。
每个小任务做完看一下，再下一个。

解药 5：留心 Cloud Agent

Cloud Agent 后台跑会持续花钱。
每次创建后给一个上限（比如"最多 30 分钟"或"最多 X 步"）。
不用的及时停掉。

解药 6：本地模型兜底

装 Ollama + qwen3-coder 或 deepseek-v3。
不重要的任务全本地跑，0 成本。

二、坑 2：AI 改坏代码

2.1 怎么发生

你让 Agent "重构这个登录"。 Agent 跑了 5 分钟，改了 12 个文件。你打开网站发现：登录不了，注册不了，连首页都白屏了。你想 undo，但是改了太多 undo 不全。你想 git reset，但是你忘了 commit。

2.2 为什么会发生

没 commit 就改：本地代码状态全乱了。
任务太大没看 diff：你不知道 Agent 改了什么。
跨文件改动多：连锁反应难复原。
测试覆盖不全：跑过测试也没法保证没事。

2.3 解药

解药 1：改之前必 commit

养成习惯：任何让 AI 改代码的对话之前，先 git commit。

git add .
git commit -m "before AI refactor"

可以让 Cursor 自动做（在第六章写规则）：

---
description: 大改之前自动 commit
alwaysApply: true
---

# 改动前自动 commit

任何"改动 > 3 个文件"的任务，开始前先：
1. 跑 git status
2. 如果有未提交改动，提示我先 commit
3. 创建一个 checkpoint commit "wip: before AI <task name>"

解药 2：看 diff 不是浪费时间

你看不懂代码也要看：

改了几个文件？
改了哪些大区域？
有没有删掉看起来重要的东西？

养成"接受改动前先扫一眼"的习惯。

解药 3：阶段性接受

不要"全部接受"，而是：

看 diff，逐个文件接受。
看一个文件 → 试一下功能 → 继续下一个。

解药 4：保留 Restore Checkpoint

Cursor 会自动给每一步建 Checkpoint。出问题时找到"上一个还能跑的"那一刻，点 Restore。

解药 5：建一个"安全分支"工作流

git checkout -b ai-experiments
# 让 AI 在这个分支随便改
# 改好的部分 cherry-pick 回 main

解药 6：写测试 + 让 AI 自测

让 AI 写测试覆盖核心功能。
改代码后让 AI 跑测试。
测试挂了不算"完成"。

三、坑 3：隐私泄漏

3.1 怎么发生

你在公司写代码，让 Cursor 帮你处理一份"客户名单 CSV"。 CSV 内容自动被发到 Cursor 服务器（或第三方模型 API）。 第二天 IT 找你谈话。

或者，你在家用本地模型，但是装了一个第三方 MCP，它偷偷把数据上传到陌生服务器。

3.2 哪些数据风险高

客户 / 用户个人信息（姓名、手机、地址）。
公司财务数据。
内部系统截图。
API key / 密码 / token。
客户合同 PDF。

3.3 解药

解药 1：理解 Cursor 的隐私模式

Cursor 设置 → Privacy → Privacy Mode。开启后：

你的代码 / 数据不被 Cursor 用于模型训练。
仍然会被发送给 LLM（除非你用本地模型）。

如果连"发送给 LLM"都不可以，必须用本地模型。

解药 2：用 Privacy Mode + 本地模型

装 Ollama + qwen3-coder / deepseek-v3-local。
在 Cursor 设置里把默认模型设成"Ollama 本地"。
这样数据完全不出网。

解药 3：敏感数据"手动脱敏"

处理客户名单前，把：

真实姓名 → "客户 1 / 客户 2"
真实手机 → "138-XXXX-1234"
真实邮箱 → "user1@example.com"

让 AI 处理"脱敏后"的数据，最后再人工映射回去。

解药 4：MCP 选官方 / 开源

Marketplace 里有 "Verified" 标记的优先。
第三方 MCP 装前看源码（GitHub）。
可疑的（star 少、维护停滞）不装。

解药 5：API key 永远在 .env

绝不在代码里写 key。 .env 加到 .gitignore。让 Cursor 写规则强制：

---
description: 禁止硬编码 API key
alwaysApply: true
---

# 严禁硬编码 secret

任何 API key / token / password 必须：
- 从 process.env / 环境变量读
- 在代码里只放占位符
- .env 文件加入 .gitignore

如果发现代码里有疑似 key（看起来像 sk_ / ghp_ / pk_ 开头），立即停下来告诉我。

解药 6：审查"哪些 MCP 在调"

Cursor 设置 → MCP → "Log all calls"。
隔几天查一下日志。
看到不该有的调用立刻 disable。

四、坑 4：依赖冲突 / 版本地狱

4.1 怎么发生

AI 给你装了一个 next@15，但是你某个老插件只支持 next@13。启动报错满屏 peer dependency conflict。你卡在那里 1 小时，删 node_modules、重装、还是错。

4.2 解药

解药 1：固定版本

package.json 里别用 ^，用精确版本：

"next": "15.0.4"   // 而不是 "^15.0.4"

升级时手动升、看 changelog。

解药 2：每次装新依赖前问 AI

让 Cursor 规则要求：

任何装新依赖前，必须告诉我：
1. 这个包做什么
2. 最新版本号
3. 和现有依赖有没有冲突
4. GitHub star / 最后更新时间

解药 3：lockfile 进 git

package-lock.json 或 pnpm-lock.yaml 必须 commit。确保团队 / 部署环境装的版本和你一样。

解药 4：冲突时让 AI 解

冲突报错时：

@File package.json
@Web 这个 peer dependency 冲突怎么解？
请给我 3 个方案，从最保守到最激进。

AI 通常能给出降版 / 加 overrides / 换替代库的方案。

五、坑 5：白屏 / 静默失败

5.1 怎么发生

AI 改完，你打开页面：白屏。F12 控制台一片红。你截图发给 AI："白屏了"。 AI 回："我看不到错误，你能给我控制台吗？"

来回 5 次还没解决。

5.2 解药

解药 1：报错完整发给 AI

不要只说"白屏"，要把：

控制台所有红字（截图 + 文字两份）
Network 标签页中的失败请求
你做了什么操作触发的

一次性发给 AI：

@File pages/index.tsx
我打开首页白屏，控制台报错：

TypeError: Cannot read properties of undefined (reading 'map')
    at HomePage (index.tsx:42:18)
    at renderWithHooks (...)

行 42 是 `data.items.map(...)`。

排查：
1. 是不是 data 还没 fetch 回来？
2. 还是 API 返回不对？

AI 拿到完整线索能 1 次定位。

解药 2：Cursor 内置浏览器

第九章提到的内置浏览器，AI 能直接看你的页面 + 看控制台。跑：

@playwright 帮我打开 localhost:3000，截图给我看，
顺便把控制台 error 全部读出来分析。

解药 3：加全局错误边界

React / Vue / Svelte 都有"错误边界"。让 AI 加一个：

帮我加全局错误边界，所有未捕获的错误显示一个友好的"出错了，刷新试试"页面，
而不是白屏。
错误信息发到 Sentry（如果接了）。

六、坑 6：过度依赖 AI、自己什么都不会

6.1 症状

离了 Cursor 你写不出 5 行代码。
看到一个 AI 给的代码，你不知道它对不对。
别人问你"这是怎么实现的"，你说"AI 写的"。
项目交付后 1 个月你打开自己的代码看不懂。

6.2 为什么严重

短期：项目能做出来。长期：

你失去了"判断 AI 输出对不对"的能力。
你失去了对项目的"主权"——某天 AI 不给力你死活推不动。
你的"市场价值"停滞——招聘者不看你"会不会用 AI"，看你"懂不懂这背后是什么"。

6.3 解药

解药 1：定期"读"AI 写的代码

养成习惯：AI 写完一段，至少把它扫一遍：

这是什么逻辑？
这个函数为什么这么写？
如果让我改一行，我能改对吗？

解药 2：5% 的时间"手写"

每周拿 5% 时间（约 2 小时）：

不开 Cursor 的 AI，纯靠自己写一个小功能。
或者读一篇 React / Tailwind 官方文档。
或者用便宜模型让 AI 教你"X 是什么"，而不是"做 X"。

解药 3：让 AI 教你

不要问 AI "改这段代码"。问 AI "为什么我之前的写法不对、新写法好在哪"。

@File index.tsx
你刚才把我的 useState 改成了 useReducer，我看不太懂。
请给我一段 200 字的说明：什么时候用 useState、什么时候用 useReducer、
你为什么觉得我这里需要 useReducer？

每次 AI 改完都问一次"为什么"，你的能力会成倍增长。

解药 4：周期性"无 AI 复盘"

每个月底，挑 1-2 个 AI 写的项目：

关掉 Cursor AI。
自己 review 一遍代码。
给自己讲 30 分钟"这个项目是怎么实现的"。
讲不出来的部分 = 你没真懂。

七、坑 7：品味退化、产出"垃圾内容"

7.1 症状

你做的网站全部"AI 味"——一样的渐变、一样的字体、一样的卡片。
你写的文案全部"AI 味"——开头总是"在如今这个时代"、结尾总是"让我们一起"。
你的项目 README 全是"项目使用了最新的技术栈"这种废话。

AI 默认输出趋于"中位数审美"——足够好但毫无个性。

7.2 解药

解药 1：先有审美再让 AI 写

收集你喜欢的网站 / 字体 / 配色，存成一个 Notepad。
让 AI 写之前，先 @ 这个 Notepad："照这个风格"。

解药 2：拒绝"AI 套话"

让 AI 规则禁止：

禁止使用：
- "在如今这个时代"
- "让我们一起 ... 吧"
- "随着 ... 的发展"
- "comprehensive solution"
- "robust and scalable"

直接说人话。

解药 3：5 个小时学一次"原作品"

每月花 5 小时不开 AI，去看：

1 本设计书（《设计的法则》《写给大家看的设计书》）
5 个你喜欢的产品（拆它的字体、颜色、间距、文案）
1 段名家文章（Paul Graham、Naval、何伟）

AI 可以让你"做出来"，但是"做得好"靠你自己的审美厚度。

解药 4：永远把"我的最后一笔"放在产品上

不论 AI 写了多少，最后 5% 一定要你亲自调：

文案：你自己改一遍，加你的语气。
视觉：你自己微调间距、颜色、对齐。
命名：你来决定按钮叫什么。

这 5% 是"AI 产品"和"你的产品"的分界线。

八、坑 8：学习停滞、不知道往哪儿走

8.1 症状

学完这本书，你能用 Cursor 做出 80% 的小项目。然后呢？

复杂项目你拿不动（架构？性能？多租户？）。
想突破"工具人"层级你不知道学什么。
看到大佬写的文章一脸懵。

8.2 12 个月学习路径

下面是普通人"用完这本书后"接下来 12 个月的路径。每月一个主题。

Month 1：消化本书

做完本书 7 个生活案例 + 8 个工作案例中的 5 个。
上线 1 个属于你的小工具（按第十一章）。

Month 2：HTML/CSS/JS 基础

MDN Web Docs 通读 HTML / CSS 基础。
油管 "JavaScript Tutorial for Beginners" 一遍。
不需要"会写"，需要"看 AI 写的能看懂"。

Month 3：选一个框架学

推荐 Next.js（React 全栈）或 SvelteKit（更易上手）。
跟着官方教程做完一个"博客"或"todo list"。
AI 协助，但你要主导。

Month 4：数据库 + API

Supabase 玩深一点：自己写 SQL、设计 schema、玩 RLS。
或者学 Prisma + Postgres。
理解"前端 / 后端 / 数据库"三件套。

Month 5：版本控制 + 协作

Git 进阶：rebase、cherry-pick、reflog、resolve conflict。
GitHub PR 流程、Code Review、Issue 管理。
跟一个开源项目，提一个 PR。

Month 6：英语 + 看文档能力

每天读 30 分钟英文技术文档。
推荐 css-tricks.com / smashing.com / josh.com。

Month 7：第一个真正"用户付费"的产品

选一个细分痛点（自己懂、别人也痛）。
第八章 "30 天 SaaS 计划"严格执行。
目标：第一笔真实付费收入。

Month 8：营销与分发

学一点 SEO（关键词、meta、内容）。
学一点设计（Figma 入门、配色基础）。
学一点文案（让 AI 帮你润色，但是你要会判断）。

Month 9：性能与可观测

Web Vitals（LCP / FID / CLS）。
Sentry 进阶用法。
学会"看慢"、"找慢"、"修慢"。

Month 10：选一个深耕方向

AI / 数据 / 设计 / 教育 / 健身 / 个人 SaaS / 内容 / 自动化……
这个方向你愿意投入下一个 5-10 年。
在这个方向做你的第二个 / 第三个产品。

Month 11：分享与教学

写 5 篇博客记录你的踩坑。
录 3 个 demo 视频上 B 站 / YouTube。
"你能讲清楚一件事"远比"你做出来"更值钱。

Month 12：复盘 + 设定下一年

看你这 12 个月做了什么、收获了什么、剩下什么遗憾。
给下一年定 3 个核心目标。
庆祝你完成了"普通人 → 独立创造者"的关键 1 年。

九、Cursor 之外：你还应该会的 5 样东西

Cursor 再厉害，它只是工具。下面 5 样是 Cursor 不能替代 的：

1. 提问能力

"会不会问问题"决定你和 AI 的协作上限。本书第五章是个起点，长期靠生活经验积累。

2. 判断力

AI 给你 3 个方案，你能判断"哪个最好"吗？这靠见识、品味、经验。

3. 执行力

AI 帮你做出来 80%，剩下 20% 是你自己跟用户聊、修小细节、坚持运营。这 20% 决定项目活不活。

4. 审美

配色、字体、文案、节奏感——AI 给你"中位数"，你要给"上四分位数"。

5. 自我管理

不被 AI 写的代码绑架、不让 AI 替你决策、不让"省下来的时间"白白流失。

十、对自己的"3 个承诺"

读到这里，请你做 3 个对自己的承诺。这不是矫情，是过来人的诚恳建议。

承诺 1：每周做出至少 1 个小东西

不论大小。一个脚本、一个网页、一段自动化。 做的多 > 想的多 > 学的多。

承诺 2：每个月让一个真实的人用上你做的东西

不必是付费。家人、朋友、同事都行。 一个真实用户的反馈 > 100 条 AI 的赞美。

承诺 3：每个季度复盘一次

3 个月一次，写 30 分钟"这个季度我学到了什么、做到了什么、下个季度要专注什么"。 复盘是普通人和高手的最大差距。

十一、最后想对你说

你刚刚读完了一本 12 章的橙皮书。如果你跟着做到了 70%，你已经：

能用 Cursor 在一个晚上做完一个小工具。
能给爸妈、朋友、同事帮上具体的忙。
有了上线一个真实产品的全部能力。
有了一个"我也能做出来东西"的信念。

这件事在 5 年前是不可能的。 2026 年的你，处在一个史无前例的时代——普通人有能力创造软件。

不要把这能力浪费在"听说就行"。

去做。每周一个。每月一个真用户。每季度一次复盘。 3 年后，你会感谢今天打开本书的自己。

本章一图回顾

8 个最容易踩的坑
═══════════════════════════════════════════════
  1. 账单爆炸     ←  日看用量 / 拆任务 / 本地模型兜底
  2. 改坏代码     ←  改前必 commit / 看 diff / 写测试
  3. 隐私泄漏     ←  Privacy Mode / 本地模型 / 数据脱敏
  4. 依赖冲突     ←  固定版本 / lockfile / AI 解
  5. 白屏静默     ←  完整报错 / 内置浏览器 / 错误边界
  6. 过度依赖     ←  读 AI 代码 / 5% 手写 / 周期复盘
  7. 品味退化     ←  先有审美 / 禁套话 / 最后 5% 自调
  8. 学习停滞     ←  12 个月路径 / 选方向深耕

12 个月成长路径
─────────────
  M1  消化本书           M7  第一个付费产品
  M2  HTML/CSS/JS        M8  营销与分发
  M3  框架（Next）        M9  性能与可观测
  M4  数据库 + API        M10 选方向深耕
  M5  Git + 协作         M11 分享与教学
  M6  英语 + 看文档       M12 复盘 + 下一年

3 个对自己的承诺
─────────────
  ① 每周做出至少 1 个小东西
  ② 每月让 1 个真实的人用
  ③ 每季度复盘 30 分钟

全书结语

这是这本书的最后一章正文。但接下来还有 5 个附录，是你长期会反复翻的速查工具：

收藏起来，需要时翻。

最后——祝你做出第一个让自己骄傲的东西。