SuperAPI AI 工具集

nextjs-deployment

前端与建站

查看项目

更新于 10-15 21:52

技能介绍

用途:为 Next.js 应用提供生产部署的模式与代码示例,覆盖 Docker 容器化、GitHub Actions CI/CD、环境配置、健康检查与生产监控。

主要能力:支持 standalone 输出模式用于容器部署,多阶段 Docker 构建优化镜像,GitHub Actions 自动化构建与推送镜像,环境变量分层管理(NEXT_PUBLIC_ 构建期与浏览器可见、无前缀仅服务端、运行时按环境注入),健康检查端点,以及基于 OpenTelemetry 的可观测性。

使用方式:在 next.config.ts 中设置 output: 'standalone';编写多阶段 Dockerfile,使用 node:20-alpine,复制 .next/standalone、.next/static 与 public,以非 root 用户运行并配置 HEALTHCHECK;在 .github/workflows/deploy.yml 中配置构建、登录镜像仓库与 build-push-action;通过 src/lib/env.ts 校验必需环境变量;在 src/app/api/health/route.ts 实现健康检查;在根目录 instrumentation.ts 中调用 registerOTel 配置监控。多服务器部署需生成并统一设置 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY,可用 openssl rand -base64 32 生成。

适用场景:需要将 Next.js 部署到容器或自托管 Node.js 服务器、搭建 CI/CD 流水线、配置预览与预发环境、接入监控与追踪的团队。

限制与警告:standalone 输出需 Node.js 18+;运行时环境变量仅在 output: 'standalone' 下生效,静态导出(output: 'export')不支持;Server Actions 加密密钥必须在所有实例间保持一致,否则多服务器部署会报错;OpenTelemetry 需在项目根目录放置 instrumentation.ts;切勿为敏感值使用 NEXT_PUBLIC_ 前缀,不要提交 .env.local;缺少健康检查可能导致编排器将流量发往不健康实例。具体平台指南与进阶配置见技能内 references 目录文档。