部署与运行配置

学习目标

代码在你机器上会跑不算数——要能在任何一台干净机器上照着文档重现。本课把环境变量、构建、迁移、启动、日志整理成一份可执行的运行手册，并以「零残留环境重现」为验收标准。

问题场景

换了台电脑想跑自己的知识站：clone 下来发现少了 .env，起了服务发现数据库表不存在，端口被占又不知道怎么改……每个坑都得重新踩一遍。这些知识只存在于你脑子里——部署配置的产出不是「能跑」，是「任何人照着文档能跑」。

核心解释

运行手册五件套，缺一不可：

1. 环境变量：列出全部变量、默认值、作用。用 .env.example（提交进库）承载模板，真实 .env 不进 git：

# .env.example —— 复制为 .env 后按需修改
REACTLAB_DATA_DIR=./data   # 数据目录（SQLite 与上传文件所在）
PORT=3000                  # 监听端口
# NODE_ENV 由 next start 自动设为 production，无需手写

2. 构建与启动顺序：装依赖 → 构建 → 迁移 → 启动，顺序错了启动即崩：

npm ci                     # 按锁文件精确安装
npm run build              # 产出 .next/
npm run db:migrate         # 建表与结构升级（空库直接到位）
npm start                  # 生产模式启动，读取 .env

3. 迁移策略：启动前跑迁移；迁移必须幂等（N15 的台账机制保证），重复执行无副作用。

4. 日志：启动日志打「监听端口、数据目录、迁移结果」三要素；运行日志记录写操作与错误堆栈。排查问题的第一现场永远是日志，不是猜测。

5. 回滚：出问题能退回上一个构建产物（保留上一版 .next 或用发布目录切换），数据靠 N13 的备份兜底——代码可回滚，数据只可恢复。

node:sqlite 的运行时要求：用到大内置模块的路由必须跑在 Node.js 运行时。App Router 默认就是 Node.js 运行时，但如果你显式声明过 export const runtime = "edge"，务必检查——edge 环境没有 node:sqlite，部署即报错。个人站自部署（VPS / Docker / 裸机 node）最省心，不必迁就平台的限制。

验收标准只有一条：干净环境重现。 找个新目录（或新容器），只带文档和代码，从零执行手册到核心功能可用。跑不通的就是文档欠账，补文档而不是口头解释。

示例拆解

本机演练（模拟干净环境）：

1. 复制工程到新目录，确认没有 .env、没有 data/、没有 node_modules。
2. 照运行手册逐条执行，记录每步输出。
3. 启动后请求首页与 /api/notes——200；数据目录自动生成——说明 DATA_DIR 配置生效。
4. 故意把 REACTLAB_DATA_DIR 指到只读路径再启动——日志里应出现清晰报错而非静默失败。

关键点：文档里每条命令都要是「可直接复制的完整命令」；出现「然后你自己看着办」的地方，就是将来出事故的地方。

动手任务

在本机工程里完成：

1. 补 .env.example，变量与代码里 process.env 的实际读取一一对应。
2. 写一份运行手册（RUNBOOK.md 或补 README）：五件套齐全，命令可复制执行。
3. 在新目录按手册从零跑到核心页面可访问，把遇到的文档缺口补齐。

常见错误

• .env 提交进 git：密钥和数据路径泄漏；模板用 .env.example，真实文件进 .gitignore。
• 迁移不进启动流程：新环境表不存在，页面全 500；「先迁移再启动」要写进手册。
• 环境变量文档与代码默认值漂移：没人说得清哪个生效；代码默认值必须同步进文档。
• 启动日志缺三要素：端口冲突、数据目录指错这类问题排查时间翻倍。

检查与复盘

自查清单：

• 干净环境照文档一次跑到核心功能可用
• 环境变量清单、默认值、作用三者一致
• 启动日志包含端口、数据目录、迁移结果

参考资料

• Next.js 文档：环境变量 —— 变量加载规则与命名约定
• Next.js 文档：部署 —— 构建产物与生产启动
• Next.js 文档：自托管 —— 自部署的注意事项