更新于 2026 年 9 月 5 日
先描述现象，不急着重装
记录访问地址、发生时间、失败页面、预期结果和实际结果。区分“部署没有完成”“页面返回错误”“页面空白”“只有某个按钮失败”。记录最近一次修改，保留日志中的第一处错误；分享日志前删除令牌、个人信息和数据库连接值。
构建失败：检查运行环境
对照本地与托管环境的运行时版本、锁文件、安装方式和构建脚本。找不到模块时，检查依赖声明和导入路径大小写，而不是不断添加新依赖。配置错误要检查项目根目录和构建产物目录是否一致。
构建通过但请求失败：看运行日志
检查启动命令、必需环境变量、数据库连接权限和服务端错误。以服务端日志为准，不将用户看到的通用错误当作完整原因。如果首页能打开但接口失败，应单独检查接口请求，而不是重写整个页面。
页面空白或资源失败：看浏览器
在浏览器开发者工具的 Console 与 Network 中检查脚本异常和失败请求。记录状态码、资源路径和触发步骤。示例：内页点击正常、刷新却 404，可能是路由托管配置问题，需要核对应用的路由方式，不应盲目把所有错误重定向到首页。
预览正常、域名异常：检查绑定
比较同一路径在预览地址和正式域名下的响应。核对域名是否绑定到正确项目、DNS 是否指向平台要求的目标、证书是否就绪，以及是否存在相互跳转。不要仅凭一次本地缓存结果反复修改 DNS。
交给 AI 的排错材料
提供技术栈、运行时版本、脱敏后的相关配置、第一处错误、复现步骤和最近改动。要求 AI 提出一个可以验证的假设、最小修改和验收步骤。每次只验证一个原因；问题解决后记录原因和修复，不只记录“重新部署好了”。