摘要
技术文章写得多，不代表踩坑就少。本文从真实项目经历出发，整理 10 个在开发、部署、审核、支付接入和 AI 协作中反复出现的坑：配置不一致、边界不清、验收缺失、密钥暴露、文档滞后、AI 过度执行等。每个坑都附带成因和可执行的避坑做法，希望读者能少走弯路，让代码和交付更稳。
写技术文章久了，会有一种错觉：好像自己已经懂很多了。
但真正做项目时，坑往往不出在那些“不会写”的地方，而出在那些“以为已经想清楚了”的地方。
下面这 10 个坑，有的来自部署，有的来自审核，有的来自和 AI 协作，有的来自自己把本地能跑误当成线上能交付。它们不高级，但足够真实，也足够疼。
坑 1：本地能跑，就等于可以上线
这是最常见、也最难戒掉的坑。
本地开发环境里，一切看起来都顺：接口通了、页面能开、功能点一遍没问题。于是心理上会觉得“差不多了，可以提审/发布了”。
但上线环境往往还有一层你没在本地完整模拟的东西：
环境变量是否齐全。
公开站点是否已部署到最新版本。
第三方平台配置是否和官网文案一致。
HTTPS、跨域、权限说明是否齐全。
审核方看到的是不是你以为的那个页面。
我后来给自己定了一条很土但很有用的规则：上线前必须有一份检查清单，而且清单里的每一项都要能在浏览器里点开验证。
不是“我觉得部署了”，而是“这个链接我现在打开确实是对的”。
坑 2：配置散落在三个地方，却以为它们会自动一致
很多项目不只有一个配置源。
代码里写一套限制。
官网写一套价格。
支付平台填一套描述。
应用商店再填一套隐私链接和支持邮箱。
你以为它们描述的是同一件事，但审核方是按“是否一致”来查的，不是按你的主观意图。
这类坑的可怕之处在于：每一处单独看都没大错，组合起来却会被拒。
避坑做法很简单：
把“产品名称、价格、邮箱、隐私政策链接、服务条款链接、功能边界”整理成一张对照表。
每次改动只改一处时，强制同步其他两处。
发布前用全文搜索确认没有旧文案残留。
配置一致性问题，不是技术难点，是纪律问题。
坑 3：把密钥和敏感逻辑放在“方便”的地方
方便的地方通常不安全。
前端代码、仓库里的.env示例、截图里的调试面板、日志里的完整请求体——这些都曾经坑过人。
尤其是涉及支付、许可证、第三方 API 时，浏览器端和公开仓库都不该成为秘密的存放点。
更稳的结构永远是：
客户端只知道自己该调哪个公开接口。
敏感校验放到服务端或边缘函数。
密钥只存在于部署平台的环境变量里。
日志里不打印 token、license key、完整身份证号。
有一次我差点把“先跑通”当成“先上线”，后来才意识到：能跑通 demo 和能安全上线，中间差了一整层架构。
坑 4：权限申请过大，却只用一句话解释用途
做需要访问页面、存储、网络的项目时，很容易陷入一种心态：先把权限申请全，后面再说。
短期省事，长期麻烦。
审核方、用户、平台规则问的不是“你能不能用到”，而是“你为什么需要用到”。
如果权限范围和实际功能对不上，再强的功能也会被质疑。
我现在写权限说明时会逼自己回答三个问题：
用户不授权时，核心功能是否仍部分可用？
这个权限对应的具体用户操作是什么？
有没有更小权限的替代方案？
能不用<all_urls>就不用，能不用宽泛 host 就不用。权限不是越多越好，而是越准越好。
坑 5：文档是上线前一天才补的
很多人把文档当“善后工作”。
隐私政策、服务条款、README、部署说明、故障排查笔记——全都等功能写完再补。
结果就是：代码是最新的，文档是过期的，或者根本没有。
而很多审核、合规、协作问题，恰恰卡在文档上。
我现在的习惯是反过来的：
需求阶段就列出“上线必须有的文档清单”。
每改一个会影响用户或审核的点，就同步改文档。
把文档当成产品的一部分，而不是附件。
文档滞后，本质上和测试滞后一样，都是把风险往后推。
坑 6：测试只覆盖“理想路径”
功能能点通，不代表功能完整。
理想路径往往只占真实使用的三分之一。剩下的是：
网络失败。
空数据。
重复提交。
状态过期。
用户中途离开页面再回来。
新旧版本数据格式不一致。
第三方接口返回非预期错误码。
如果只测“点一下按钮有反应”，上线后很容易接到“偶发”“有时候”“某个用户说不行”这类难复现问题。
我现在会给每个功能至少补三类测试视角：
成功路径。
失败路径。
中断/恢复路径。
不一定都要写成自动化测试，但脑子里必须有这张表。否则你以为测过了，其实只是测了一种情况。
坑 7：部署成功，不等于线上已更新
这是运维里很阴的一种坑。
你明明执行了部署命令，控制台也显示成功，但用户访问到的还是旧页面。
原因可能是：
部署到了错误项目。
浏览器/CDN 缓存了旧资源。
只更新了 Worker，没更新静态站。
只更新了静态站，没更新 API。
生产环境和测试环境域名搞混。
所以我现在不把“部署命令退出码为 0”当完成标准。
我会再做一个动作：用无缓存方式打开线上地址，搜索本次改动必须出现的关键词。
比如价格、邮箱、某个新页面标题。搜不到，就说明线上还没真正更新。
坑 8：让 AI 直接改代码，却不给边界和验收标准
这两年踩过最多的新坑，其实和 AI 有关。
不是 AI 不能用，而是用法太像“许愿”。
“帮我优化一下。”
“把这个模块重构得更健壮。”
“检查一下有没有问题。”
这些话对人来说可能够，对 Agent 来说太虚。
于是很容易出现：
改了很多文件，但问题没解决。
方案看起来专业，但不符合项目实际。
顺手重构了不该动的模块。
测试没跑，却宣布完成。
我现在用 AI 时强制加三样东西：
边界：哪些能改，哪些不能改。
目标：什么叫完成，要能观察。
验收：测试、构建、手动检查项。
AI 不是不能干活，而是不能在没有契约的情况下干活。
坑 9：把 AI 输出当成事实，不做二次验证
AI 很会组织语言，这既是优点也是风险。
它可以把一个不确定的猜测说得很像结论。
比如：
“这个接口应该返回 200。”
“这个字段名大概率是userId。”
“这个错误通常是 CORS 导致的。”
听起来都对，但未必对你的项目成立。
我现在把 AI 输出分成两类：
假设：需要我去代码、日志、文档里验证。
结论：已经有证据支撑，可以据此行动。
只要没验证，就当假设，不当结论。这样能少踩很多“看起来很对”的坑。
坑 10：追求速度，却忽视回滚意识
最后一个坑，和心态有关。
项目赶进度时，很容易想“先上去再说”。
但复杂系统里，能上线和能安全撤回同样重要。
没有回滚意识时，你会倾向于：
一次改太多。
不保留变更说明。
不基于分支操作。
不记录环境差异。
出问题后不知道从哪里开始查。
我现在哪怕是一个人做项目，也会尽量保留：
明确的提交说明。
可识别的部署版本。
关键配置变更记录。
出问题时的第一排查路径。
不是为了形式主义，而是为了出错时不用靠记忆救火。
这 10 个坑背后的共同点
回头看，这 10 个坑其实共享几个根因：
把“局部成功”误认为“整体完成”。
把“当前能跑”误认为“已经验证”。
把“我知道”误认为“系统里已经写清楚”。
把“快”放在“稳”前面。
技术成长，很多时候不是学会更多框架，而是更早识别这些模式。
我现在的避坑习惯
说几个我现在真的在用的习惯，不复杂，但有效。
上线前固定过一张 checklist，价格、邮箱、链接、权限、构建结果都在上面。
涉及第三方审核时，先查“一致性”，再查“功能”。
用 AI 前先写边界和验收，不让它直接大改。
部署后一定打开线上地址做关键词验证。
每个功能至少想一遍失败路径，不只看 happy path。
文档跟代码一起改，不拖到最后一刻。
密钥、隐私、日志三件事单独过一遍。
出问题先问“最近改了什么”，而不是先加新功能。
这些习惯不酷，但比多会两个框架更能保命。
写在最后
CSDN 上文章很多，真正有价值的往往不是“我又学了某个 API”，而是“我这次为什么翻车，以及下次怎么不再翻”。
技术坑不会因为你写过几篇博客就自动消失。
但只要开始记录、开始对照、开始把隐性经验变成显性 checklist，踩坑的次数就会明显下降。
代码更稳，很多时候不是因为写得更快，而是因为翻车更早被拦住。
如果你也在做独立项目、接平台审核、用 AI 协作开发，希望这 10 个坑能帮你少交一点学费。
)
