foka-ci/docs/pitfalls.md

踩坑指南 (Pitfalls)

1. Prisma 客户端生成

• 现象: 修改 schema.prisma 后代码报错找不到类型。
• 解决: 需要在 apps/server 下运行 pnpm prisma generate。本项目将生成的代码放在了 generated/ 目录而非 node_modules，请注意引用路径。

2. zx 环境变量继承

• 现象: 在流水线脚本中找不到 node 或 git 命令。
• 解决: PipelineRunner 在调用 zx 时必须手动扩展 env: { ...process.env, ...userEnv }，否则会丢失系统 PATH。

3. Koa BodyParser 顺序

• 现象: 获取不到 ctx.request.body。
• 解决: koa-bodyparser 中间件必须在 router 中间件之前注册。

4. SQLite 并发写入

• 现象: 部署日志极快输出时偶发 SQLITE_BUSY。
• 解决: 适当增加 better-sqlite3 的 busy timeout。