故障排查

​

排查原则

1. 环境变量是否正确
2. 数据库是否可连
3. 内容文件是否合规
4. 同步是否成功
5. 页面是否读取到了预期数据源

​

问题一：/admin/login 总是失败

​

现象

​

排查

1. 检查 .env 是否有 ADMIN_PASSWORD
2. 确认运行进程读取的是最新环境变量
3. 重启服务后再次尝试

​

问题二：同步命令报错

​

命令

​

排查

1. 先执行 npm run content:sync:dry
2. 根据报错定位到具体 MDX 或 JSON 文件
3. 检查 frontmatter 必填字段与日期格式

​

问题三：页面数据没有更新

​

排查

1. 确认已经执行同步
2. 确认数据库中记录状态是 PUBLISHED
3. 清理浏览器缓存并刷新
4. 检查当前环境是否在文件回退模式

​

问题四：数据库迁移失败

​

排查

1. 确认数据库容器已启动
2. 校验 DATABASE_URL
3. 使用 Prisma 命令检查状态：

npx prisma migrate status

​

问题五：构建失败

​

排查

1. 先执行 npm run lint
2. 再执行 npm run test
3. 最后执行 npm run build
4. 根据首次报错优先修复，不要同时改多处

​

快速健康检查命令

npm run lint
npm run test
npm run build