本节目标：建立安全开发的阶段意识，遇到问题时能快速定位和解决。
安全相关的报错往往让人一头雾水——错误信息不直观，原因可能在你意想不到的地方。小明踩过的每一个坑，都变成了这本手册里的一条。遇到问题？按症状查。
.env 配置了但读不到。 症状是 process.env.XXX 返回 undefined。先重启——环境变量只在启动时加载，Ctrl+C 停掉服务重新 pnpm dev，90% 的问题到这里就解决了。还不行的话，检查变量名拼写是否完全一致（注意大小写），确认 .env 文件在项目根目录（不是在 src/ 里），检查有没有多余的空格或引号——.env 里不需要引号，DATABASE_URL=postgresql://... 是对的，DATABASE_URL="postgresql://..." 可能出问题。
Server 能读到但 Client 读不到。 症状是 API Route 里能读到环境变量，React 组件里是 undefined。原因是没加 NEXT_PUBLIC_ 前缀——这是 Next.js 的安全机制，默认不把环境变量发送到浏览器。如果这个值确实需要在前端使用且不敏感，改名为 NEXT_PUBLIC_XXX。如果是敏感值（API Key），不应该在前端使用——改为在 API Route 里调用。
跨域报错（CORS）。 症状是浏览器控制台显示 Access to fetch at 'xxx' has been blocked by CORS policy。如果前后端在同一个 Next.js 项目里，不应该出现 CORS 问题——检查请求 URL 是否写错了（比如写了完整的 http://localhost:3000/api/... 而不是相对路径 /api/...）。如果调用的是外部 API，需要在后端配置 CORS，允许你的域名访问。有时候是开发环境特有的问题，检查 next.config.js 里的 rewrites 配置。
.gitignore 配了但文件仍被追踪。 症状是 .env 已加入 .gitignore，但 git status 仍然显示它。原因是文件在加入 .gitignore 之前已经被 Git 追踪过——.gitignore 只对"从未被追踪的文件"生效。解决方法是执行 git rm --cached .env 移除缓存，再提交一次。
密钥已经泄露了。 症状是密钥被提交到了 GitHub（公开或私有仓库）。紧急处理四步走：立即去对应平台（OpenAI、Supabase、GitHub 等）重新生成密钥；用新密钥更新 .env；告诉 AI "我的 .env 文件被提交到了 Git 历史中，帮我用 git filter-branch 或 BFG 工具彻底清除"；检查账单是否有异常消费。
git rm .env 然后提交，只是在最新版本里删除了文件。Git 历史中的每一个旧版本仍然包含这个文件。任何人 git log 都能找到。必须清洗历史。
登录后仍被重定向到登录页。 症状是登录成功了，但访问受保护页面还是跳转到 /login。先检查 Cookie 是否正常设置——打开浏览器 F12 → Application → Cookies，看有没有 session cookie。然后确认域名一致——开发环境用 http://localhost:3000，不要用 http://127.0.0.1:3000，Cookie 绑定域名，域名不同 Cookie 不共享。最后检查 Middleware 的 matcher 配置，确认没有把 /login 也保护了（登录页不应该被保护）。
你不需要记住所有这些检查项。定期让 AI 帮你审查：
"审查我的项目安全状况：检查是否有硬编码密钥、.env 是否被 Git 追踪、依赖是否有已知漏洞、所有受保护路由是否都有权限检查。"
.gitignore，开发中检查边界和校验，上线前审计依赖，上线后定期轮换.env 问题重启就能解决.gitignore 只对未追踪的文件生效，已追踪的要先 git rm --cached清单和排查手册都有了，接下来去 进阶安全防护——了解 SQL 注入、XSS、CSRF 等更深层的安全威胁，以及 AI 应用特有的安全问题。