更新升级
如何从上游拉取最新更改、重新运行代码生成器以及处理破坏性变更。
标准更新工作流
每次从主分支拉取新提交后，请运行以下命令：
git pull origin mainpnpm install拉取后务必重新运行 pnpm install。新增的包或版本升级不会自动生效。
pnpm db:migrate当 packages/platform/db/prisma/migrations/ 中有新的迁移文件时运行此命令。即使没有待执行的迁移，运行也是安全的。
pnpm db:generate当 packages/platform/db/prisma/schema.prisma 发生变化时需要运行此命令。生成的客户端已被 gitignore，必须在本地重新生成。
将所有四个步骤合并为一个命令，方便使用：
git pull && pnpm install && pnpm db:migrate && pnpm db:generate检查破坏性变更
在拉取主版本升级之前，请阅读更新日志中的所有破坏性变更。
常见的破坏性变更类型：
| 类别 | 需要关注的内容 |
|---|---|
| Schema 变更 | 新增必填列、重命名表、删除索引 |
| 包 API 变更 | @nebutra/* 包中的重命名导出、更改的函数签名 |
| 环境变量 | @nebutra/config 中新增的必填环境变量 |
| 构建系统 | turbo.json、tsconfig.base.json 或 biome.json 的变更 |
何时需要重新运行 pnpm db:generate
当以下任一内容发生变化时，需要重新生成 Prisma 客户端：
packages/platform/db/prisma/schema.prismapackages/platform/db/prisma/migrations/（新迁移文件）packages/platform/db/package.json中的prisma版本
pnpm db:generate如果 Schema 文件没有变化，则拉取代码后不需要重新生成客户端。如果不确定，可以运行 git diff packages/platform/db/prisma/schema.prisma 查看。
何时需要重新运行 pnpm generate:api-types
当 API 网关的 OpenAPI 规范发生变化时，需要重新生成 OpenAPI TypeScript 类型：
pnpm generate:api-types生成的类型位于 apps/web/src/lib/api/types.generated.ts，通过 apps/web/src/lib/api/client.ts（getTypedApi）和 apps/web/src/lib/api/browser-client.ts（browserApiClient）中的 openapi-fetch 消费。仓库中提交了 stub 以便生成前也能通过 typecheck，CI 会覆盖它。
需要重新生成的信号：
- 关于缺少 API 请求/响应类型的 TypeScript 错误
backends/gateway/src/routes/中新增了端点- 现有端点的签名发生了变更
Turborepo 缓存失效
Turborepo 会缓存任务输出以加速构建。如果更新后看到陈旧的构建产物，请强制执行干净的重新构建：
pnpm turbo run build --force要完全清除本地缓存：
pnpm turbo prune --scope=@nebutra/ui # 删除特定包的缓存
rm -rf .turbo # 核弹选项：清除所有本地缓存Vercel Remote Cache 用于 CI/CD。本地缓存和远程缓存是独立的 — 清除本地缓存不会影响 CI 构建。
依赖升级
升级 workspace 中的单个依赖：
pnpm update --filter @nebutra/ui react交互式升级所有过期包：
pnpm update --interactive --recursive任何依赖升级后，请运行完整验证套件：
pnpm typecheck && pnpm lint && pnpm test && pnpm build相关内容
How is this guide?
最后更新于