如何构建SSR模式的Nuxt3项目并部署至线上托管服务？

一、前置配置检查 #

• 确认nuxt.config.ts的渲染模式：确保ssr: true（Nuxt3默认开启，若被修改需恢复），同时配置正确的DRF后端API地址：

  export default defineNuxtConfig({
    ssr: true,
    runtimeConfig: {
      // 服务端专用的敏感配置（如DRF认证密钥）
      apiSecret: process.env.DRF_API_SECRET,
      // 客户端/服务端通用的公开配置
      public: {
        apiBase: process.env.NUXT_PUBLIC_API_BASE || 'https://your-drf-api-domain.com/api'
      }
    }
  })
  

• 同步项目依赖：执行npm install或yarn install，更新依赖到兼容版本，避免因依赖冲突导致构建失败。

二、SSR生产构建命令 #

执行以下命令完成生产环境SSR构建：

npm run build
# 或使用yarn
yarn build

构建完成后，项目根目录会生成.output文件夹，这是SSR部署的核心产物。

三、本地预验证（推荐） #

构建后本地启动服务，验证SSR功能与接口调用是否正常：

npm run preview
# 或
yarn preview

访问http://localhost:3000，检查页面是否由服务端渲染，且能正常请求DRF接口数据。

四、线上托管部署操作 #

通用部署流程（适配多数Node.js托管服务） #

1. 上传文件：将.output文件夹、package.json、package-lock.json（或yarn.lock）上传至托管服务。
2. 配置环境变量：在托管服务的环境变量面板中设置：
   • NUXT_PUBLIC_API_BASE：你的DRF后端公网API地址
   • 若有服务端敏感配置（如DRF_API_SECRET），同步添加对应环境变量
3. 设置启动命令：托管服务需执行启动SSR服务的命令，标准命令为：

   node .output/server/index.mjs
   

主流托管服务额外配置 #

• Vercel：无需手动配置启动命令，平台会自动识别Nuxt3 SSR项目，仅需上传代码并配置环境变量。
• Netlify：在项目根目录创建netlify.toml文件，指定构建与路由规则：

  [build]
    command = "npm run build"
    publish = ".output/public"
  [[redirects]]
    from = "/*"
    to = "/.netlify/functions/server"
    status = 200
  [functions]
    directory = ".output/server"
  

• Docker自定义部署：创建Dockerfile打包镜像，部署到自有服务器：

  FROM node:18-alpine
  WORKDIR /app
  COPY .output/ .output/
  COPY package.json package-lock.json ./
  RUN npm install --production
  EXPOSE 3000
  CMD ["node", ".output/server/index.mjs"]
  

五、常见问题排查 #

• 构建失败：查看终端报错信息，重点排查依赖缺失、API地址配置错误，或代码中在服务端渲染时调用了仅客户端可用的API（如window对象），需用process.client做环境判断：

  if (process.client) {
    // 仅在客户端执行的代码
    console.log(window.location.href)
  }
  

• 部署后页面空白：检查托管服务的端口配置是否为3000，或环境变量中DRF API地址是否正确，确保服务端能正常访问后端接口。

内容的提问来源于stack exchange，提问作者developers