构建、迁移与部署

学习目标

读完本课你能：在干净环境按序完成安装、迁移、种子、构建、启动五步；说清每步在做什么、失败时看什么；核对环境差异（Node 版本、环境变量、可选工具链）不靠碰运气。

问题场景

新机器（或半年后的你）接手这个项目：npm run dev 一跑，报错连成串——依赖没装齐、数据库还是空的、AI 配置缺失、Go 没装。一条条试错修了半小时。这些坑其实是同一条流程的固定五步，每步有明确的前置和验证，本课把本站的真实流程写成可复制的操作单。

核心解释

本站从零到运行的完整流程（每步可直接复制执行）：

# 0. 前置：记录 Node 版本（Next 16 需要较新的 Node）
node -v

# 1. 安装：按 package-lock.json 精确安装（E01 的可复现原则）
npm ci

# 2. 数据库迁移 + 内容种子：建表 + 把 content/ 内容灌进库
npm run db:seed

# 3. 生产构建
npm run build

# 4. 生产启动（http://localhost:3000）
npm run start

第 2 步拆开看（最容易黑盒的一步）：db:seed 运行 scripts/seed.ts，先 migrate() 依次执行 lib/db/migrations/ 下的 SQL（建表语句带 IF NOT EXISTS，幂等，跑多少次都安全），再把 content/ 里的课程、题目、练习 upsert 进库（可重复执行，内容更新后重跑即可，个人学习数据不动）。数据库文件在 data/database/reactlab.db——旁边的 -wal、-shm 是 SQLite WAL 模式的正常附属文件，不是垃圾。

环境差异核对单：

可选依赖的设计值得注意：lib/runner/local.ts 的 checkToolAvailable 会先探测解释器，缺失时给出「请安装 Python 3 并加入 PATH」的明确提示，其余功能照常——必要依赖（Node、数据库）与增强依赖（Python/Go）分层，装不上后者不该挡住前者。

示例拆解

两个必做的破坏性验证（确认流程真的可重复）：

# 验证 1：删库重建——迁移与种子真的幂等吗？
npm run db:reset    # 实际动作：删除整个 data/database 目录
npm run db:seed     # 重新建表 + 灌内容 → 课程页应完好如初
# 注意：个人学习数据（笔记、进度）会随之清空——这正是它的用途，执行前想清楚

# 验证 2：内容更新传播——改了 content/ 之后怎么生效？
# （改动某课程 mdx 之后）
npm run content:check   # 结构校验（E01 检查链的一环）
npm run db:seed         # upsert 新内容进库
# 刷新页面 → 新内容可见；这就是「内容更新流程」的全部（E08 会写成制度）

关键点：db:reset 与 db:seed 的分工——reset 是「回到空白」的破坏性操作（删 data/database），seed 是「可重复灌装」的安全操作（upsert）。日常改内容只用后者；前者留给「想彻底重来」的时刻。

动手任务

1. 在本机按五步流程从 npm ci 开始完整走一遍，记录每步耗时与输出关键行。
2. 执行验证 1（删库重建），确认课程内容完好；如果本机有重要学习数据，先备份 data/database。
3. 人为弄坏一个前置（比如临时改错 .env.local 里的服务地址），观察故障出现在五步中的哪一步、错误信息是否指向根因。

常见错误

• 用 npm install 代替 npm ci：依赖按范围重新解析，装出来的版本可能和锁文件不同，「在我机器上能跑」由此产生。
• 迁移写成不幂等的 SQL：没有 IF NOT EXISTS 的建表第二次跑就炸；迁移必须「跑 N 次结果一样」。
• 改了 content 忘了 re-seed：页面读的是数据库不是文件，改完不灌库，改动「不生效」还以为代码有 bug。
• 把 data/ 当内容仓库：data/database 是运行时数据，学习数据没有版本管理，删库前先备份——内容与数据永远分开对待。

检查与复盘

• 五步流程能默写顺序，每步说得出「做什么、失败看哪」
• 迁移幂等、种子可重复，都动手验证过
• 环境差异核对单四项逐一通过，可选依赖缺失时明确知道影响范围

参考资料

• Next.js 官方：Self-hosting —— 自托管部署的官方指引
• npm 官方：npm ci —— 精确安装的语义与前提
• SQLite 官方 —— 数据库文件、WAL 模式与附属文件的权威说明