部署

恭喜！您已准备好部署 Next.js 应用。本页将展示如何使用 Next.js 构建 API 进行托管或自托管部署。

Next.js 构建 API

next build 会为生产环境生成优化后的应用版本。标准输出包括：

• 使用 getStaticProps 或 自动静态优化 的页面 HTML 文件
• 全局样式或独立作用域样式的 CSS 文件
• 用于 Next.js 服务端预渲染动态内容的 JavaScript
• 通过 React 实现客户端交互性的 JavaScript

这些输出生成在 .next 文件夹中：

• .next/static/chunks/pages – 此文件夹中的每个 JavaScript 文件对应同名路由。例如 .next/static/chunks/pages/about.js 会在访问 /about 路由时加载
• .next/static/media – 从 next/image 静态导入的图片会经过哈希处理后复制到此目录
• .next/static/css – 应用中所有页面的全局 CSS 文件
• .next/server/pages – 服务端预渲染的 HTML 和 JavaScript 入口点。启用 输出文件追踪 时会生成 .nft.json 文件，包含页面依赖的所有文件路径
• .next/server/chunks – 应用中多处复用的共享 JavaScript 代码块
• .next/cache – 构建缓存和 Next.js 服务器缓存的图片、响应及页面输出。使用缓存可减少构建时间并提升图片加载性能

.next 内的所有 JavaScript 代码都已编译，浏览器捆绑包也已压缩，以实现最佳性能并支持 所有现代浏览器。

使用 Vercel 托管 Next.js

Vercel 是零配置部署 Next.js 应用的最快方式。

部署至 Vercel 时，平台会 自动识别 Next.js，运行 next build 并为您优化构建输出，包括：

• 跨部署持久化未变更的缓存资源
• 每次提交生成 不可变部署 的唯一 URL
• 尽可能对 页面 自动进行静态优化
• 从 全球边缘网络 提供压缩后的资源（JavaScript、CSS、图片、字体）
• 将 API 路由 自动优化为可无限扩展的独立 无服务器函数
• 将 中间件 自动优化为 边缘函数，实现零冷启动和即时加载

此外，Vercel 还提供以下功能：

• 通过 Next.js 速度分析 自动监控性能
• 自动 HTTPS 和 SSL 证书
• 通过 GitHub、GitLab、Bitbucket 等实现自动 CI/CD
• 支持 环境变量
• 支持 自定义域名
• 支持通过 next/image 进行 图片优化
• 通过 git push 实现即时全球部署

免费将 Next.js 应用部署至 Vercel 试用体验。

自托管部署

您可以使用 Node.js 或 Docker 自托管 Next.js 并支持所有功能。也可选择 存在部分限制 的静态 HTML 导出方案。

Node.js 服务器

Next.js 可部署至任何支持 Node.js 的主机提供商，例如 AWS EC2 或 DigitalOcean Droplet。

首先确保 package.json 包含 "build" 和 "start" 脚本：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

然后运行 npm run build 构建应用，最后执行 npm run start 启动 Node.js 服务器。该服务器支持 Next.js 所有功能。

如果使用 next/image，建议在生产环境中通过 npm install sharp 安装 sharp 以获得更高效的 图片优化 性能。Linux 平台可能需要 额外配置 以防止内存占用过高。

Docker 镜像

Next.js 可部署至任何支持 Docker 容器的主机提供商。此方案适用于部署到 Kubernetes 或 HashiCorp Nomad 等容器编排器，或在任何云提供商的单节点中运行。

1. 在机器上 安装 Docker
2. 克隆 with-docker 示例
3. 构建容器：docker build -t nextjs-docker .
4. 运行容器：docker run -p 3000:3000 nextjs-docker

如需在不同环境使用不同环境变量，请参考我们的 with-docker-multi-env 示例。

静态 HTML 导出

如需将 Next.js 应用导出为静态 HTML，请遵循 静态 HTML 导出文档 的指引。

其他服务平台

以下服务支持 Next.js v12+ 版本。您可找到各服务的部署示例或指南。

托管服务器

• AWS Copilot
• Digital Ocean 应用平台
• Google Cloud Run
• Heroku
• Railway
• Render

须知：部分托管平台允许使用 上文示例 中的 Dockerfile 方案。

仅限静态部署

以下服务仅支持通过 output: 'export' 部署 Next.js。

• GitHub Pages

您也可通过 GitHub Actions、Jenkins、AWS CodeBuild、Circle CI、Azure Pipelines 等 CI/CD 管道，将 output: 'export' 的输出手动部署至任何静态托管提供商。

无服务器部署

• AWS Amplify
• Azure Static Web Apps
• Cloudflare Pages
• Firebase
• Netlify
• Terraform
• SST

须知：并非所有无服务器提供商都实现了 next start 的 Next.js 构建 API。请确认提供商支持的功能列表。

自动更新

部署 Next.js 应用后，您希望无需重载即可看到最新版本。

路由时，Next.js 会在后台自动加载应用的最新版本。对于客户端导航，next/link 会暂时作为普通 <a> 标签使用。

须知：如果新页面（旧版本）已被 next/link 预取，Next.js 将使用旧版本。导航至未预取（且未在 CDN 层缓存）的页面将加载最新版本。

手动优雅关闭

自托管时，您可能需要在服务器收到 SIGTERM 或 SIGINT 信号时执行关闭代码。

您可设置环境变量 NEXT_MANUAL_SIG_HANDLE 为 true，然后在 _document.js 文件中注册信号处理器。注意需直接在 package.json 脚本中注册该变量，而非 .env 文件。

须知：next dev 不支持手动信号处理。

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "NEXT_MANUAL_SIG_HANDLE=true next start"
  }
}

if (process.env.NEXT_MANUAL_SIG_HANDLE) {
  // 应在自定义 _document 中添加此代码
  process.on('SIGTERM', () => {
    console.log('Received SIGTERM: ', 'cleaning up')
    process.exit(0)
  })

  process.on('SIGINT', () => {
    console.log('Received SIGINT: ', 'cleaning up')
    process.exit(0)
  })
}