使用 Vercel 部署 create-t3-appT3 全栈 Next.js 应用的仪表盘与 CLI 部署实战【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-appcreate-t3-app 生成的 T3 应用是构建在 Next.js 之上的全栈、类型安全工程而 Vercel 正是官方文档首推的部署平台——它对 Next.js 应用的开箱即用支持可以极大简化生产环境上线流程。本文基于 ru/deployment/vercel.md 的技术内容结合本仓库中生成的模板与配置源码完整讲解通过 Vercel Dashboard 图形界面与 Vercel CLI 命令行两种方式部署 T3 应用的全过程并深入说明vercel.json项目配置与DATABASE_URL等环境变量在部署中的关键作用。读完本文你将能够独立把 create-t3-app 工程推送到生产环境并理解其背后的 env 校验机制。为什么推荐用 Vercel 部署 T3 应用官方文档明确建议将 T3 应用部署到 Vercel原因是它让部署 Next.js 应用变得极其简单。这一推荐的底气来自两个层面框架同源Next.js 由 Vercel 团队开发维护平台对 Next.js 的构建、边缘函数、增量静态再生成ISR等特性支持最完整部署 T3 应用几乎不需要额外适配。仓库本身的实践佐证本仓库的文档站www/目录本身就是通过 Vercel 部署的其 www/vercel.json 配置了字体文件的长效缓存头Cache-Control: public, max-age31536000, immutable、cleanUrls以及/docs、/discord、/github等路由重定向是vercel.json在实际项目中的真实用法示例。项目配置vercel.json 与自动检测绝大多数项目无需任何配置Vercel 在导入项目时会自动检测框架并推断构建命令build command与发布目录publish directory。对于使用 create-t3-app 生成的标准工程其 cli/template/base/package.json 中已经定义了完整的 npm scriptsscripts: { dev: next dev --turbo, build: next build, start: next start, preview: next build next start, typecheck: tsc --noEmit }Vercel 会自动识别next build作为构建命令因此在大多数项目中完全不需要手动配置。需要手动指定时的 vercel.json 写法如果希望显式声明这些配置例如与团队统一约定、或覆盖自动检测结果可以在项目根目录创建vercel.json文件写入如下配置{ buildCommand: npm run build, outputDirectory: dist, devCommand: npm run dev, installCommand: npm install }各字段含义如下字段含义默认行为buildCommand生产构建命令对应npm run build即next build自动检测outputDirectory构建产物目录Next.js 默认为.next自动检测devCommand本地开发命令对应npm run dev自动检测installCommand依赖安装命令对应npm install自动检测需要说明的是create-t3-app 支持 npm / pnpm / yarn / bun 四种包管理器见 cli/src/utils/getUserPkgManager.ts若项目使用 pnpm可将installCommand相应改为pnpm install。Vercel 同样会自动识别锁文件并选择合适的包管理器。使用 Vercel Dashboard 图形化部署无需任何命令行知识通过 Vercel 网页控制台即可完成首次部署全程共四步第 1 步创建新项目。将代码推送到 GitHub 仓库后使用 GitHub 账号注册/登录 Vercel点击Add New Project添加新项目。第 2 步导入仓库。在项目列表中选择包含 T3 应用的 GitHub 仓库并导入Vercel 会自动完成框架检测。第 3 步配置环境变量。在部署设置中为项目添加环境变量——这是 T3 应用能否成功构建和运行的关键具体变量说明见下文环境变量一节。第 4 步点击 Deploy。部署完成后只要后续向仓库推送代码变更Vercel 便会通过 Git 集成自动触发重新部署实现持续部署CI/CD。使用 Vercel CLI 命令行部署对于偏好终端工作流的开发者Vercel 提供了官方 CLI。首先全局安装npm i -g vercel在项目根目录执行vercel命令即可发起部署vercel首次运行时 CLI 会引导你登录账号、关联项目并确认部署配置。携带环境变量部署DATABASE_URL数据库连接字符串这类环境变量可以通过--env参数在命令行中直接传入vercel --env DATABASE_URLYOUR_DATABASE_URL_HERE --yes其中--yes表示跳过交互式提问对所有部署问题直接采用默认答案适合在 CI 脚本中无阻塞执行。部署到生产环境需要特别注意首次部署之后的vercel命令默认只会部署到预览preview分支供联调与评审使用。要直接推送到线上正式站点必须追加--prod标志vercel --prod这意味着日常开发迭代可以先用预览部署验证确认无误后再用vercel --prod发布到生产。环境变量Vercel 上的 DATABASE_URL 与 env 校验机制T3 应用的 env 校验原理create-t3-app 通过t3-oss/env-nextjs与 zod 在构建期校验环境变量。以 cli/template/base/src/env.js 为例import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { NODE_ENV: z.enum([development, test, production]), }, client: { // NEXT_PUBLIC_CLIENTVAR: z.string(), }, runtimeEnv: { NODE_ENV: process.env.NODE_ENV, }, skipValidation: !!process.env.SKIP_ENV_VALIDATION, emptyStringAsUndefined: true, });它把服务端变量与客户端变量NEXT_PUBLIC_前缀分离声明一旦缺失必需变量next build会直接失败。这意味着在 Vercel 上配置环境变量不是可选项而是部署成功的硬性前提。需要配置哪些变量脚手架在生成项目时会同步生成.env与.env.example两个文件逻辑见 cli/src/installers/envVars.ts。以数据库为例常见变量形如# Prisma DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/你的项目名 # Next Auth AUTH_SECRET # Better Auth BETTER_AUTH_SECRET在 Vercel 上有两种配置途径Dashboard在项目的 Settings → Environment Variables 中添加可区分 Production / Preview / Development 三套环境分别赋值CLI使用上文vercel --env DATABASE_URL...传入。安全要点.env 永不入库cli/template/base/_gitignore 中明确忽略了.env与.env*.local只允许提交不含密钥的.env.example同时.vercel目录也被 gitignore 忽略避免本地部署元数据进入版本库。因此生产环境变量必须以 Vercel 控制台或 CLI 注入而不是写入仓库。预览/生产环境变量分离的实用建议由于DATABASE_URL等变量往往区分本地开发、预览分支与生产环境建议在 Vercel 中按环境分别配置预览环境使用数据库的临时/测试实例生产环境使用正式实例避免误操作污染生产数据。部署后的验证与常见问题完成部署后可通过以下方式验证打开 Vercel 分配的项目域名确认页面正常渲染在 Dashboard 的 Deployments 中查看构建日志npm run build即next build应成功退出若构建时报环境变量缺失错误回到 Settings → Environment Variables 补齐后再触发一次 Redeploy。常见问题速查现象原因与解决构建失败提示 env 校验错误未配置对应环境变量在 Vercel 中补充DATABASE_URL、AUTH_SECRET等推送代码后线上无变化确认仓库已关联 Vercel 且推送的分支是部署配置中的生产分支vercel命令只更新了预览站需追加--prod才会部署到生产本地可用、线上连不上数据库检查DATABASE_URL指向的数据库是否对 Vercel 的网络开放访问且使用正确的 SSL 参数至此你已经掌握了将 create-t3-app 工程部署到 Vercel 的完整链路无论是 Dashboard 的图形化四步流程还是 CLI 的vercel/vercel --prod命令组合配合正确的vercel.json项目配置与环境变量注入T3 应用即可实现随 Git 提交自动更新的持续部署。【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考