故障排查

先确定问题范围

按下面的顺序检查：

1. 对照来源版本、README 和交付检查清单，确认当前使用的命令和配置属于同一交付版本。
2. 查看问题是在未修改的基础版本中就存在，还是修改产品后才出现。
3. 确认本地、测试和生产环境分别使用了哪组环境变量与第三方账号。
4. 只保留一个可以稳定复现问题的操作，再查看对应服务的错误信息。

依赖无法安装

• 确认 Node.js 版本符合当前交付版本 README。
• 在仓库根目录运行安装命令，不要在单个包中建立另一套依赖。
• 确认源码文件和锁文件来自同一个交付版本。
• 如果自行升级过依赖，先比较升级前后的安装结果。

本地服务无法启动

• 确认依赖安装已经完成。
• 使用 README 提供的产品级开发命令。
• 检查错误是否明确指出缺少环境变量、端口占用或外部服务不可用。
• 如果基础版本可以启动，逐批撤回最近修改，定位引入问题的模块。

环境变量没有生效

产品变量应放在：

products/01mvp/packages/config/.env.local

共用默认配置放在：

packages/config/.env.local

产品配置会覆盖同名共用配置。修改后重新启动开发服务。不要把生产密钥写进前端公开变量、提交到 Git，或复制到公开文档中。

登录失败

• 确认该登录方式已经启用，并配置了对应凭据。
• 检查第三方平台中的回调地址是否与当前域名和协议完全一致。
• 分开检查本地、测试和生产环境，不要共用错误的回调地址。
• 查看身份验证文档确认当前源码的配置入口。

数据库错误

• 确认当前环境连接的是自己的数据库，不是交付说明中已经移除的生产数据库配置。
• 检查数据库迁移是否与当前代码版本一致。
• 更新源码后先审阅迁移内容，再应用到测试环境。
• 查看数据库文档确认迁移和连接方式。

支付或订单状态异常

• 确认商品、价格和支付渠道属于同一环境。
• 检查支付回调地址、签名密钥和订单查询使用的账号。
• 本地页面成功跳转不代表支付回调已经到达服务器。
• 查看支付集成文档逐项核对。

本地正常，部署后失败

• 对照本地与生产环境变量，确认生产环境没有缺项。
• 检查正式域名、登录回调、支付回调和邮件发件域名。
• 查看运行环境的构建日志、启动日志和健康检查结果。
• 查看部署与运维文档确认当前目标的部署要求。

找不到技术说明

本组文档只说明网站源码的购买后流程。架构、登录、数据库、支付和部署等深度文档位于 /docs/template。

如果问题属于交付范围、来源版本或授权清单，保留错误信息、使用的版本和复现步骤，再按订单说明联系交付方。