摘要技术文章写得多不代表踩坑就少。本文从真实项目经历出发整理 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 个坑能帮你少交一点学费。