01 · 项目搭建与运行：先把环境连起来#
本章目标：让当前仓库在本机运行，并能解释 Node.js、Next.js、PostgreSQL、Prisma 各自做了什么。先完成运行，再理解配置，避免一开始被工具名称淹没。
1. 我们正在搭建什么#
前端项目常见的运行方式是“浏览器 + 开发服务器”。这个项目多了一个真正保存业务数据的 PostgreSQL：
浏览器 ──HTTP──> Next.js（页面 + 接口）──数据库连接──> PostgreSQL
│
└──当前完整版本还包含后台任务──> Redis + WorkerNext.js 在同一个仓库中组织页面和服务端入口；这不代表浏览器可以直接操作数据库。数据库连接串、登录密钥和业务权限判断仍属于服务端。
第一阶段的主线依赖 Next.js 与 PostgreSQL。当前版本创建工单还会在数据库保存提醒任务；Redis 与 Worker 负责后续执行这些任务。理解基础 CRUD 时可以先不启动 Worker，但若要完整运行当前应用，应把它一并启动。
2. 确认环境和版本#
为了与仓库 CI 和 Dockerfile 保持一致，本教程统一使用 Node.js 24、pnpm 12.10.1 与 Docker Desktop。先检查：
node --version
pnpm --version
docker --version
docker compose versionDocker Desktop 需要处于运行状态；安装了命令行但引擎没启动，也无法启动数据库。
本仓库 package.json 声明 pnpm@12.10.1，Next.js 为 16.4.2，React 为 19.3.0，Prisma 为 7.10.1。这些是本项目的版本依据，不是要求你把其他项目统一升级到这些版本。其余依赖常用 ^ 范围，具体安装结果由 pnpm-lock.yaml 固定。
拓展阅读为什么要提交锁文件？
package.json 可以表达“允许哪些版本”；锁文件记录实际选中了哪一组依赖。两个人都执行安装时，锁文件帮助他们获得一致结果。复现现有仓库时，优先安装仓库依赖，不要照着教程逐个安装 latest。
如果要理解从空目录搭建的顺序，可以把它看成：Next.js + TypeScript + App Router 骨架 → UI 与 Provider → 数据库与 Prisma → 共享校验 → tRPC → 工单页面。这个仓库已经完成这些步骤，跟学时无需再次执行脚手架，也不要在项目内嵌套生成另一个应用。
3. 安装依赖与准备配置#
进入现有仓库：
cd /Users/chen/Documents/work/coding/nextjs-mvp
pnpm install --frozen-lockfile安装脚本包括 postinstall 的 prisma generate 和 prepare 的 Husky 配置。前者生成数据库访问代码，后者配置 Git hook；这一步还没有创建业务表。
首次配置、且没有 .env 时执行：
cp .env.example .env
node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))"将随机输出填入 .env 的 BETTER_AUTH_SECRET。如果已有 .env，直接对照示例补齐缺项，避免覆盖自己的配置。随机输出是密钥，不要提交进 Git。
| 变量 | 用途 | 本地注意事项 |
|---|---|---|
DATABASE_URL |
服务端连接 PostgreSQL | 示例连宿主机 localhost:5433 |
BETTER_AUTH_SECRET |
认证库使用的私密配置 | 填入独立随机值，至少 32 字符 |
BETTER_AUTH_URL |
认证使用的应用地址，也用于业务请求来源检查 | 默认 http://localhost:3000，与浏览器访问地址一致 |
REDIS_URL |
当前队列使用的 Redis 连接 | 示例 redis://127.0.0.1:6380 |
QUEUE_PREFIX |
区分队列命名空间 | Web 与 Worker 使用同一个值 |
LOG_LEVEL |
Worker 日志级别 | 学习时保留 info 即可 |
pnpm dev 将服务绑定到 127.0.0.1，但浏览器可以按示例打开 http://localhost:3000。不要随意把访问地址换成 127.0.0.1:3000 而保留旧的 BETTER_AUTH_URL；主机名不同会影响 Cookie 与来源检查。
拓展阅读环境变量不等于公共变量。
数据库连接串只应在服务端读取。Next.js 的 NEXT_PUBLIC_ 前缀用于允许公开到浏览器的配置，不要给密钥加这个前缀。.gitignore 已忽略真实 .env，示例文件则保留在仓库中。
4. 启动数据库并执行迁移#
pnpm db:up
pnpm db:migrate第一条执行 docker compose up -d --wait，按 compose.yaml 启动 PostgreSQL 与 Redis，并等待健康检查。第二条执行 prisma migrate deploy，把仓库已有迁移应用到目标数据库。
本地端口关系是：
| 服务 | 宿主机端口 | 容器内端口 | 本机 Node.js 进程访问 |
|---|---|---|---|
| PostgreSQL | 5433 | 5432 | localhost:5433 |
| Redis | 6380 | 6379 | 127.0.0.1:6380 |
把容器想成一台有自己端口空间的小机器。5433:5432 表示把本机 5433 转给容器的 5432；本机启动的 Next.js 应连前者。后续部署到容器网络时地址规则不同，不要照搬本机连接串。
三个容易混淆的 Prisma 操作#
| 操作 | 改什么 | 什么时候用 |
|---|---|---|
pnpm db:generate |
根据 schema 生成 Prisma Client 和类型 | 安装后、模型更新后 |
pnpm db:migrate |
执行已有 SQL 迁移，改变数据库结构 | 首次搭建、拉取新迁移后 |
pnpm exec prisma migrate dev --name 描述 |
在开发环境根据模型差异生成并应用新迁移 | 你实际开发新模型时；本教程无需执行 |
generate 像根据接口定义生成 SDK；migrate 像给真正的数据仓库施工。生成了 SDK，不代表表已经存在。migrate deploy 只执行已有迁移，不会替你把任意 schema 修改自动变成 SQL。
本项目把连接地址配置放在 prisma.config.ts，客户端生成目录设在 prisma/schema.prisma 的 src/generated/prisma；运行时通过 @prisma/adapter-pg 接入 PostgreSQL。不要照抄其他 Prisma 版本的初始化代码覆盖它。
数据库数据保存在 Docker volume，停止容器并不删除数据。日常暂停可执行 docker compose stop；不要为了处理普通报错直接删除 volume。
5. 启动 Web 与 Worker#
终端一：
pnpm dev终端二，在相同项目目录：
pnpm worker打开 本地应用 ↗，注册账号并登录，创建一个团队。创建团队后你成为该团队管理员，因此可以练习完整的状态修改链路。数据库迁移不会自动产生演示账号或演示工单。
Web 接收用户请求；Worker 独立执行后台任务。关闭网页不会停止 Worker，停止 Worker 也不等于关闭 Web。基础工单操作不要求 Redis 同时在线，后台提醒与导出则需要它恢复后才能处理；实现细节留到后续阶段。
6. 看懂工程配置#
| 文件或命令 | 解决的问题 | 本阶段关注点 |
|---|---|---|
tsconfig.json |
TypeScript 与 @/ 别名 |
@/shared/ticket 指向 src/shared/ticket |
eslint.config.mjs / pnpm lint |
静态规则、React / Next.js 使用检查 | 发现代码写法问题 |
.prettierrc.json / pnpm format:check |
统一格式 | 与类型检查职责不同 |
pnpm typecheck |
next typegen + tsc --noEmit |
生成路由类型再检查项目 |
vitest.config.mts / pnpm test |
执行测试 | 未设测试连接时跳过对应集成用例 |
| Husky + lint-staged | 提交前检查暂存文件 | 提交 hook 不替代完整验证 |
| commitlint | 检查提交信息结构 | 例如 docs: 添加第一阶段学习教程 |
pnpm build |
生成 Prisma Client，再进行生产构建 | 仓库指定 --webpack，开发则用 Turbopack |
next.config.ts 还包含 cacheComponents、partialPrefetching、standalone 和服务端外部依赖配置。先知道它们分别涉及渲染、预取和部署即可；它们不等于浏览器里的 TanStack Query 缓存，也不会替我们检查工单权限。
7. 本章验收#
完成以下动作，才算环境搭建闭环：
docker compose ps中数据库和 Redis 健康，pnpm db:migrate成功。- 能注册、登录、创建团队，进入工单工作台。
- 创建一张“无法登录”的工单，刷新页面仍能看见。
pnpm db:studio中能找到对应Ticket记录，标题与页面一致；查看即可，先通过业务接口练习修改。- 能解释：
pnpm install安装依赖，generate生成访问代码，migrate建表，dev启动应用。
遇到问题时先读 第 06 章排错表，再回到下一章理解代码结构。