从零搭建 Next.js Turborepo 全栈项目（含…

当需要端到端创建一个全新的 Next.js turborepo 项目（含 Blode UI、图标、Ultracite 代码检查、工作区钩子、GitHub 与 Vercel 部署）时使用。

适用场景

解决思路

1. Phase 1 收集项目信息：向用户询问缺失的变量——{{name}}（必填，如 acme-web）、{{description}}（必填）、{{repo}}（必填，如 acme-corp/acme-web）、{{domain}}（缺失则询问）、{{author}}（必填）、{{year}}（默认当前年份）。
2. Phase 2 创建 Next.js 应用：严格按 references/app-setup.md 中的 create-next-app 命令执行（其中固定了 linter、React Compiler 和包管理器标志）；确认应用在服务器报告的端口上可加载；3000 被占用时使用任务专属的空闲端口。
3. Phase 2.1 升级到 TypeScript 7：安装 typescript@^7，并确认 npm run build 通过 tsc 完成类型检查；无需额外配置。
4. Phase 2.2 开启 Instant Navigations：在 next.config.ts 中设置 cacheComponents、partialPrefetching 和 experimental.turbopackRustReactCompiler；在任何路由存在之前完成（此处便宜、后期昂贵）；在 Phase 3 前阅读该节的编写规则，它们约束每个页面的写法。
5. Phase 3 安装 Blode UI 组件与图标：执行 shadcn init，注册 @blode 命名空间，在 components.json 中设置 iconLibrary，安装 blode-icons-react，然后添加组件。
6. Phase 4 安装 Agentation：安装包，在 app/layout.tsx 中加入仅开发环境的 <Agentation /> 守卫；可选通过 @next/third-parties 添加 Google Analytics。
7. Phase 5 安装 Ultracite：用指定标志运行 ultracite@latest init，包括 --js-plugins @shadcn/lint（Ultracite ≥ 7.12）；用 npx ultracite fix 和 npx ultracite check 验证；它生成的 lefthook.yml 是临时的，Phase 6 会用根级文件替换。
8. Phase 5.1 启用 ultracite/oxlint/shadcn：确认 init 已将 import shadcn from "ultracite/oxlint/shadcn" 写入 extends（与 core/next/react 并列）；若没有则手动添加该 import（以及 jsPlugins: shadcn.jsPlugins）；不要手写 jsPlugins: ["@shadcn/lint"] 或仅 starter 的 no-restyle 规则；该预设已在 **/components/ui/** 内关闭 shadcn/no-restyle，仅当 aliases.ui 指向其他路径时才添加匹配的 override。
9. Phase 6 转换为 Turborepo：把应用移入 apps/web/（命令见 references/app-setup.md 末尾），然后按 references/turbo-configs.md 操作：(1) 从模板生成根 package.json、turbo.json、lefthook.yml、knip.json 和 .gitignore，删除 apps/web/lefthook.yml（git 只读取 .git 旁的副本）；(2) 将 apps/web/package.json 脚本更新为 turbo 兼容块并移除其 prepare 脚本（根脚本负责安装钩子）；(3) 确认 apps/web/next.config.ts 仍有 reactCompiler: true、cacheComponents: true、partialPrefetching: true；(4) 从模板写根 AGENTS.md，把 Phase 5.1 的设计系统 lint 段落保留在 apps/web/AGENTS.md 的 Next 管理标记之外，包括 ultracite fix / ultracite fix --codex；(5) 从根运行 npm install，再从编码代理的 shell 运行一次 npm run dev——Next 16.3 检测到编码代理时会把管理的 nextjs-agent-rules 块追加到 apps/web/AGENTS.md（某些生成器还会创建 CLAUDE.md 包装），提交 AGENTS.md 并删除重复的 CLAUDE.md 包装；普通终端不会写入，这没关系，该块会在代理首次运行时出现；(6) 从根验证 npm run check、npm run build 和 npx lefthook run pre-commit --all-files 通过，然后 npm run start -w web 并从生产构建加载首页。
10. Phase 7 GitHub 与 Vercel 设置：按 references/deploy-and-launch.md，用 gh 创建 GitHub 仓库，部署到 Vercel，绑定 {{domain}}。
11. Phase 8 上线前检查清单：按 references/deploy-and-launch.md，添加 CI workflow，将 metadataBase 设为 https://{{domain}}，在 Search Console 和 Bing 注册站点，添加 security.txt、favicon 包和 OG 图片，然后运行该文件末尾的验证清单；只有所有验证项通过才算完成，“站点能加载”不是充分证据。
12. 占位符清理：模板使用 {{variable}} 语法；Phase 7 前用 grep -rn '{{' --include='*.json' --include='*.ts' --include='*.tsx' --include='*.md' --include='*.yml' . 扫描遗漏的占位符；package.json 中残留 {{name}} 会导致 npm install 失败（invalid-name 错误），metadata 中残留 {{domain}} 会发布损坏的 OG URL；根 package.json 模板中有两个占位符不在 Phase 1 收集：{{ultracite_version}} 从 ultracite init 写入 apps/web/package.json 的 ultracite 条目复制，{{npm_version}} 是 npm --version 的输出。
13. 不要创建 src/ 目录：脚手架使用 --no-src-dir，之后添加 src/ 会破坏 @/* 别名和所有 shadcn 组件路径。
14. 永远不要设置 experimental.useTypeScriptCli：自 16.3 起 CLI 检查器是默认，该标志只用于用 false 关掉它，设为 true 是噪音且读起来像需求。
15. 预期 CLI 检查器给出原始 tsc 诊断：没有 Next.js 代码帧，且检查完整 tsconfig.json 项目（含测试和 .next/dev/types），因此 next build 以前跳过的文件中的类型错误现在会阻塞构建；若之后添加 node --test 文件，要么保持类型干净，要么把 **/*.test.ts 加入 tsconfig.json 的 exclude。
16. next build 通过不代表导航即时：Instant navigation 验证仅在开发环境运行（validationLevel: 'warning'）且从不使构建失败，因此要在 next dev 中验证并阅读 overlay。
17. 使用 cacheComponents: true 时，任何导出 dynamic、dynamicParams、revalidate 或 fetchCache 的路由段都会使构建失败；runtime、maxDuration、instant 和 prefetch 仍有效；这包括手写的 robots.txt/route.ts 等路由处理器；把数据访问放在单独的 'use cache' 函数中并配合 cacheLife，由页面或 GET 调用；该指令不能直接放在 GET 导出上。
18. 'use cache' 在 serverless 主机上是每实例内存缓存，因此在 Vercel 上一个函数调用中计算的值不会被下一个调用看到；文档的答案是必须共享的内容用 'use cache: remote'；sitemap 背后的数据和任何列表页都用它，廉价可重算的值保留普通 'use cache'。
19. Cache Components 下 generateStaticParams 必须返回至少一个参数；空数组会抛出 empty-generate-static-params；未列出的参数首次访问得到 App Shell 并在后台升级。
20. Cache Components 会保持前一路由的 DOM 挂载（React <Activity>），因此挂在 body 或 html 上的背景或主题（包括 body:has(.marker) 规则）会泄漏到下一路由；按路由拥有背景，主题切换在 React 中用 usePathname() 作为 key，而不是 body 上的 class；下拉和表单状态也会跨导航存活，需在 effect 中清理或从 URL 派生。
21. 永远不要添加 output: "standalone"：它用于自托管，在 Vercel 上会阻止写入 .next/next-server.js.nft.json，导致构建编译每个页面后在 Vercel 的 onBuildComplete 中死亡。
22. 永远不要设置 runtime = "edge"：它在 16 中已弃用，且 Cache Components 需要 Node.js；对于必须比响应存活更久的工作（分析、日志），使用 next/server 的 after() 而不是浮动 promise，后者在响应发出时可能被 Node 切断。
23. 不要添加 Turbopack 缓存配置：turbopackFileSystemCacheForDev、turbopackFileSystemCacheForBuild 和内存驱逐（'auto'）在 16.3 中默认开启。
24. 此处不需要 turbopack.root：Turbopack 从 lockfile 推断工作区根；仅当链接包位于仓库外时才设置。
25. next dev 会把管理的 <!-- BEGIN:nextjs-agent-rules --> 块追加到 next 包旁的 AGENTS.md（即 apps/web/，不是根），且仅当两个文件都不存在时才写入 CLAUDE.md 作为 @AGENTS.md；它仅在环境中检测到编码代理时运行（next/dist/server/lib/generate-agent-files.js），普通终端从不触发；保留 AGENTS.md，删除生成的 CLAUDE.md 包装，并把项目指令保留在标记之外。
26. create-next-app --react-compiler 会把 babel-plugin-react-compiler 安装为 devDependency；开启 experimental.turbopackRustReactCompiler 后它无用，Phase 2.2 后移除，以免被读作需求。
27. ultracite init --skip-install 会写入 check 和 fix 脚本，设置 "type": "module"，并添加 oxlint、oxfmt、lefthook 和 @shadcn/lint（最后一个来自 --js-plugins）；它不写 prepare 脚本（那发生在被跳过的安装步骤）；提交前把那些工具固定到首次 npm install 解析出的版本，并让根 prepare 负责钩子安装；确认 ultracite ≥ 7.12（npm ls ultracite --depth=0），更旧的 CLI 会拒绝 --js-plugins @shadcn/lint 或跳过预设；JS 插件需要 Oxlint ≥ 1.80 和 Node ≥ 20.19；若插件加载失败，升级 oxlint 而不是从 extends 中删除 shadcn。
28. 不要 ESLint 或 Prettier：Ultracite 通过 Oxlint + Oxfmt 负责 lint 和格式化；残留的 .eslintrc 会让编辑器与 lefthook pre-commit 钩子不一致；向 ultracite init 传 --js-plugins @shadcn/lint（Ultracite ≥ 7.12），这是 7.12 注册 ultracite/oxlint/shadcn 的方式；不要用 jsPlugins: ["@shadcn/lint"] 加仅 starter 的 shadcn/no-restyle 块替换该预设。
29. 保留 Ultracite 的 extends（core、next、react）和 ignorePatterns，并添加 shadcn；用 README 的 .oxlintrc.json 示例替换 oxlint.config.ts 会丢掉框架预设；在根配置上保留 jsPlugins: shadcn.jsPlugins：Oxlint 已从预设加载插件，但 Knip 只读取根上的 jsPlugins，否则会把 @shadcn/lint 标记为未使用。
30. 该预设在 **/components/ui/** 内关闭 shadcn/no-restyle、no-arbitrary-values 和 require-static-classes；除非 components.json 的 aliases.ui 指向别处，否则不要重复该 override；若指向别处，则为该路径添加匹配 override，否则插件会报告定义文件在自我样式化。
31. 通过工作区脚本运行 lint 和格式化：根 npm run check / npm run fix（turbo 在 apps/web 内运行它们），或从 apps/web 运行 npx ultracite check；从仓库根运行 ultracite、oxlint 或 oxfmt 找不到那里的 oxlint.config.ts，会用默认值 lint，与钩子不一致并跳过 shadcn 预设；ultracite fix 后剩余的设计系统发现可从 apps/web 交给 npx ultracite fix --codex（或 --claude）。
32. 不要手动 git 钩子：Lefthook 负责它们；husky 或其他钩子管理器会重复运行或跳过修复。
33. lefthook.yml 位于仓库根、.git 旁；apps/web/ 内的副本仅当从该目录调用 lefthook 时才被读取，而 git 钩子从不这样做；根文件用 root: "apps/web/" 限定每个 job，使暂存路径相对于工作区传递，那里有 oxlint.config.ts 和 oxfmt.config.ts。
34. 钩子把 oxfmt 和 oxlint 作为两个独立 job 运行，各有自己的 glob，而不是 ultracite fix；当暂存集不含可 lint 的 JS/TS 文件时 Ultracite 会非零退出，因此仅 CSS 或仅 Markdown 的提交会直接使钩子失败；两个 job 让 lefthook 跳过无事可做的那个；oxfmt 的 glob 包含 md 和 mdx，以便检查 format:check 所检查的内容。
35. 根 package.json 中不要放应用依赖（根只放 turbo、ultracite 和 lefthook）；它们破坏工作区隔离和 turbo 缓存键；@shadcn/lint 留在 apps/web 与 oxlint.config.ts 一起；在根和 apps/web 中固定相同的 ultracite 版本（≥ 7.12），以免配置解析漂移。
36. 永远不要在 npx shadcn@latest registry add @blode=... 之前运行 npx shadcn@latest add @blode/...；未注册的命名空间会使 add 失败。
37. 永远不要从 lucide-react 导入；blode-icons-react 是 Blode UI 的图标库，混合导入会打包两套图标；shadcn init 会把 "iconLibrary": "lucide" 写入 components.json，在添加组件前改为 blode-icons-react，并替换任何生成的 lucide-react 导入路径。
38. 永远不要手工创建 apps/web/：先在根脚手架，然后在 Phase 6 移入；手工构建会跳过 create-next-app 默认值（Tailwind 接线、别名配置）。
39. next-env.d.ts 是生成的，属于 .gitignore（create-next-app 已列出）；不要提交或编辑它；自定义声明放在从 tsconfig.json 引用的单独 .d.ts 中。
40. Next.js 从应用目录（apps/web/）加载 .env.local，而不是 turborepo 根；拉取命令是 vercel env pull apps/web/.env.local，且只有 NEXT_PUBLIC_ 变量在构建时内联到达浏览器。
41. node --test 直接运行测试文件时 @/ 别名不解析；测试文件及其导入的模块使用相对路径，测试脚本用 glob 匹配 lib/**/*.test.ts 而不是指定单个文件，否则新测试永远不会执行而门禁报告绿色。
42. 根 .gitignore 忽略 .claude/ 但取消忽略 .claude/knowledge/（以及 apps/web/.claude/）；知识文件是这些技能挖掘的记忆，实验输出才是忽略的目的。
43. 仪表盘部署前检查 Vercel Root Directory；出现 404 或应用错误时，在 Settings > General 中把 Root Directory 设为 apps/web。
44. 技能交接：部署后优化 SEO 运行 seo；上线前审计 UI 质量运行 ui-design（Audit 模式）；上线前添加动效和动画运行 ui-animation。
45. 仅维护用：evals/evals.json 包含此技能变更的回归场景；它不会在用户任务期间加载。

适用边界 · 注意事项

• 不是从零搭建全新 Next.js turborepo 时：搭建 TypeScript CLI 或 npm 包请用 scaffold-cli；为现有应用设计文件夹结构或模块契约请用 codebase-architecture；在现有应用内构建页面请用 ui-design；选择视觉方向和调色板请用 ui-design。
• 需要自托管或边缘运行时部署时：不要添加 output: "standalone"，也不要设置 runtime = "edge"（16 中已弃用且 Cache Components 需要 Node.js）。
• 环境缺少 shell、Git、Node.js、pnpm 或包注册表访问时无法执行。