企业官网建设流程全解析

create-t3-app 新项目初始化指南：数据库同步与 NextAuth Discord 登录配置

【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app

本文是 create-t3-app 的“第一步”实战指南。当你使用 T3 Stack（Next.js + TypeScript + tRPC + Tailwind CSS，可选 Prisma/Drizzle 与 NextAuth.js）脚手架创建完一个新项目后，还有几项强制性的初始化工作必须完成，否则项目无法正常运行。读完本文，你将掌握：如何用npx prisma db push同步数据库并恢复 Prisma Client 的类型安全、如何启动本地 Docker 数据库容器，以及如何从零配置 NextAuth.js 的 Discord Provider，让应用具备真实可用的登录能力。

项目创建完成后的“强制性”步骤

在 create-t3-app 中，脚手架只是生成了代码骨架。根据你在交互式 CLI 中选择的技术栈，项目里可能包含数据库（Prisma 或 Drizzle）和认证（NextAuth.js），而这两者都依赖外部服务与环境变量才能真正运行。本文依据文档 www/src/pages/ar/usage/first-steps.md（同主题英文版见 www/src/pages/en/usage/first-steps.md）展开，核心结论是：在运行npm run dev之前，先完成数据库同步和认证环境变量配置。

数据库：让 Schema 与数据库保持同步

使用本地 Docker 数据库（MySQL / PostgreSQL）

如果你在创建项目时选择了 MySQL 或 PostgreSQL 作为数据库，脚手架会生成一个名为start-database.sh的 Bash 脚本，用于在本地创建一个 Docker 容器作为开发数据库。该脚本由安装器 dbContainer.ts 在项目初始化时生成，其中project1占位符会被替换为你项目的 sanitize 后名称（非法字符替换为下划线并转小写，以符合 Docker 容器命名规范）。

脚本的核心逻辑（见 postgres.sh）：

• 从.env中的DATABASE_URL解析出密码、端口与数据库名（依次用awk按:、@、/分隔提取）；
• 自动检测并优先使用docker，其次podman，并要求 daemon 处于运行状态；
• 若指定端口已被占用（通过nc检测）则中止；容器已存在但停止时会直接docker start复用；
• 若密码还是默认值password，脚本会提示是否用openssl rand -base64 12生成随机密码并写回.env（macOS 上sed -i ''与其他平台略有差异）；
• 最终以-p "$DB_PORT":5432映射端口启动docker.io/postgres镜像。

用法很简单：

./start-database.sh

如果你已经有现成的数据库，可以直接删除该文件，把数据库连接凭据写进.env即可（macOS 用户不想用 Docker 也可以借助 DBngin 这类工具）。注意：脚本依赖.env文件中的DATABASE_URL，因此请先确认环境变量已配置。

Prisma：npx prisma db push

如果项目包含 Prisma，必须在项目根目录运行：

npx prisma db push

该命令会做两件事：

1. 将prisma/schema.prisma中的 Schema 与数据库结构同步（建表/改表）；
2. 基于当前 Schema 重新生成 Prisma Client 的 TypeScript 类型，保证数据库访问层类型安全。

重要提示：执行完这条命令后，需要重启 TypeScript 服务（在 VS Code 中可通过Ctrl/Cmd + Shift + P执行 “TypeScript: Restart TS Server”），否则 IDE 无法识别新生成的类型。

从实现上看，Prisma 安装器 prisma.ts 会在项目里注册如下 npm scripts：

因此你完全可以运行pnpm db:push（或对应包管理器命令）替代npx prisma db push。

若你同时选择了 NextAuth.js，生成的 Schema（见 with-auth.prisma）会额外包含Account、Session、User、VerificationToken四个 NextAuth 必需的模型，Post模型则通过createdBy外键关联到User。注意 MySQL/Planetscale 下需要取消@db.Text注释以容纳长 token。另外，脚手架还注册了postinstall: prisma generate，即npm install之后 Client 类型会自动就位。

Drizzle：db:push

如果项目选择的是 Drizzle，请先打开.env，按注释说明构造DATABASE_URL（不同数据库对应不同驱动，例如 postgres 用postgres包、mysql 用mysql2、sqlite 用@libsql/client，见 drizzle.ts）。环境变量就绪后运行：

pnpm db:push

对应实现是drizzle-kit push。脚手架同样注册了db:generate（drizzle-kit generate）、db:migrate（drizzle-kit migrate）、db:studio（drizzle-kit studio）脚本。drizzle 的配置见 drizzle-config-postgres.ts，其tablesFilter使用${scopedAppName}_*前缀过滤表，schema 指向./src/server/db/schema.ts，URL 从env.DATABASE_URL读取。

认证：配置 NextAuth.js 的 Discord Provider

如果你的应用包含 NextAuth.js，脚手架默认内置了DiscordProvider——这是 NextAuth.js 支持的、配置成本最低的 Provider 之一，但依然需要你手动完成一些初始设置。如果你倾向其他服务商（GitHub、Google 等），也可以使用 NextAuth.js 提供的众多 Provider，配置思路与此一致。

从源码看，认证相关的文件由 nextAuth.ts 安装：App Router 项目会生成 API 路由 route.ts（导出GET、POSThandlers），认证配置则写入src/server/auth/config.ts。默认配置 base.ts 已经预置了DiscordProvider与一个把token.sub注入 session 用户id的 callback，因此你只需要提供三个环境变量即可完成登录闭环。

第 1 步：创建 Discord 应用

你需要一个 Discord 账号（没有就先去注册）。登录后访问 Discord 开发者平台，点击右上角的New Application创建应用，填写应用名称并同意服务条款。

第 2 步：进入 OAuth2 设置页

应用创建成功后，进入Settings → OAuth2 → General页面。

第 3 步：填入 Client ID

复制页面上的Client ID，添加到项目根目录.env文件中：

AUTH_DISCORD_ID=你的Discord应用ClientID

第 4 步：重置并复制 Secret

点击Reset Secret（出于安全考虑，Discord 不再直接展示原始 Secret，需重置后复制），把新生成的 Secret 填入.env：

AUTH_DISCORD_SECRET=你的Discord应用ClientSecret

第 5 步：添加重定向回调地址

点击Add Redirect，填入本地开发回调地址：

http://localhost:3000/api/auth/callback/discord

这个地址必须与脚手架生成的 API 路由路径src/app/api/auth/[...nextauth]/route.ts（Pages Router 为src/pages/api/auth/[...nextauth].ts）保持一致。最后点击Save Changes保存。

第 6 步：配置 AUTH_SECRET

在.env中添加AUTH_SECRET（一个任意字符串）：

AUTH_SECRET=随意但足够长的字符串

生产环境务必使用强随机密钥（例如openssl rand -base64 32生成的值）。它用于加密 session cookie，泄露意味着认证体系被攻破。同时注意.gitignore已默认忽略.env（模板中的_gitignore会处理），不要把密钥提交进版本库。

生产部署的差异

本地开发回调是http://localhost:3000/...；部署到生产环境时，需要按同样步骤再创建一个 Discord 应用（或修改现有应用），把回调地址中的localhost:3000替换为你实际的部署域名（如https://your-app.com/api/auth/callback/discord），并同步更新AUTH_DISCORD_ID、AUTH_DISCORD_SECRET与AUTH_SECRET。

环境变量的运行时校验

create-t3-app 使用@t3-oss/env-nextjs+ zod 在启动时校验环境变量，基础模板见 env.js：服务端变量缺失或类型不合法会导致构建失败，从而把“配置错误”挡在运行之前。两个实用开关值得注意：

• SKIP_ENV_VALIDATION：构建或启动时设置该环境变量可跳过校验（对 Docker 等无法提供完整 env 的场景很有用）；
• emptyStringAsUndefined: true：空字符串会被当作未定义处理，避免SOME_VAR=''侥幸通过校验。

配置完成后重新启动开发服务器（npm run dev/pnpm dev），你应该就能在页面上看到 Discord 登录入口并完成登录。

验证登录与编辑器环境

登录流程打通后，可以确认 session 中包含由 callback 注入的user.id（类型层面已在 base.ts 的模块扩展中声明）。若使用 Prisma，登录数据会写入前面提到的Account/Session/User表。

为了获得更顺畅的开发体验，官方推荐安装以下编辑器扩展：

• Prisma Extension：Prisma Schema 的语法高亮与格式化支持；
• Tailwind CSS IntelliSense Extension：Tailwind 类名的智能补全；
• Prettier Extension：配合项目内置的格式化配置（prettier.config.mjs）保持代码风格统一。

下一步可以做什么

完成上述初始化后，你的 T3 App 已经具备运行条件。接下来可以：

• 若项目包含 tRPC，阅读src/server/api/routers/post.ts与对应页面，了解 tRPC query 是如何串联服务端与客户端的；
• 浏览 create-t3-app 文档站的其他使用指南（环境变量、tRPC、Tailwind、Prisma 等，均在 www/src/pages 下按语言组织），以及你所用包自身的官方文档；
• 参考 folder-structure-app.mdx 理解 App Router 下的目录职责划分，方便后续扩展业务代码。

一句话总结本文要点：先跑npx prisma db push（或pnpm db:push）同步数据库并重启 TS 服务，再按“创建 Discord 应用 → 填写 ID/Secret → 添加回调地址 → 配置 AUTH_SECRET”的顺序完成认证初始化，你的 T3 项目就能立即进入开发状态。

【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app