如何在Azure中正确部署含客户端/服务端组件的混合型Next.js应用？

方案1：Azure App Service（推荐，全特性支持） #

这是适配Next.js App Router、服务端组件、API路由、Server Actions及Next Auth的最优选择，兼容性最稳定。

• 部署前置准备

  • 在next.config.js中启用standalone输出（Next.js 12+支持），减少部署体积并优化运行效率：

    /** @type {import('next').NextConfig} */
    const nextConfig = {
      output: 'standalone',
      // 其他项目配置
    }
    module.exports = nextConfig
    

  • 本地验证生产构建：执行npm run build + npm start，确认服务端组件渲染、API调用、Next Auth登录流程均正常。

• 部署操作步骤

  1. 创建Azure App Service实例，选择Linux环境（Windows对Next.js standalone支持不佳），运行时选择与项目匹配的Node.js版本。
  2. 配置部署渠道：推荐用GitHub Actions自动部署——在App Service的「部署中心」绑定GitHub仓库与分支，Azure会自动生成适配Next.js的Workflow文件；也可通过Azure CLI手动部署：

     az webapp up --sku B1 --name <你的应用名称> --runtime "NODE|20-lts"
     

  3. 配置环境变量：在App Service的「配置」→「应用程序设置」中添加所需变量，比如NEXTAUTH_URL（设为你的App Service域名，如https://yourapp.azurewebsites.net）、NEXTAUTH_SECRET、数据库连接字符串等。
  4. 功能验证：部署完成后访问域名，逐一测试服务端组件、API接口、Next Auth认证流程。

方案2：Azure Container Apps（适合容器化需求场景） #

如果项目需要自定义运行环境，或需与其他Azure服务深度集成，可采用容器化部署方式。

• 操作步骤
  1. 编写适配Next.js的Dockerfile（官方推荐模板）：

  FROM node:20-alpine AS base
  
  # 安装依赖阶段
  FROM base AS deps
  RUN apk add --no-cache libc6-compat
  WORKDIR /app
  COPY package.json package-lock.json* ./
  RUN npm ci
  
  # 构建项目阶段
  FROM base AS builder
  WORKDIR /app
  COPY --from=deps /app/node_modules ./node_modules
  COPY . .
  RUN npm run build
  
  # 生产运行阶段
  FROM base AS runner
  WORKDIR /app
  ENV NODE_ENV production
  RUN addgroup --system --gid 1001 nodejs
  RUN adduser --system --uid 1001 nextjs
  
  COPY --from=builder /app/public ./public
  COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
  COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
  
  USER nextjs
  EXPOSE 3000
  ENV PORT 3000
  CMD ["node", "server.js"]
  

  2. 构建镜像并推送到Azure Container Registry（ACR）。
  3. 在Azure Container Apps中创建应用，选择ACR中的镜像，配置环境变量（同App Service要求），设置端口为3000。
  4. 配置自定义域名与SSL证书，完成后验证所有功能。

方案3：Azure Static Web Apps（仅适配Edge Runtime场景） #

你之前遇到的问题源于Static Web Apps对App Router服务端组件的原生支持有限，它更适合纯静态导出或基于Edge Runtime的Next.js应用。若坚持使用该方案：

• 关键配置调整
  • 所有服务端逻辑强制使用Edge Runtime：在组件或API路由顶部添加export const runtime = 'edge'。
  • Next Auth适配Edge环境：修改auth.ts配置Edge适配器：

    import NextAuth from "next-auth"
    import { AzureADProvider } from "next-auth/providers/azure-ad"
    import { EdgeConfig } from "next-auth/adapters"
    
    export const { handlers, auth, signIn, signOut } = NextAuth({
      providers: [AzureADProvider({/* 你的提供商配置 */})],
      adapter: EdgeConfig(),
      runtime: 'edge',
      // 其他Next Auth配置
    })
    

  • 部署配置：在Static Web Apps的构建设置中，指定构建命令为npm run build，输出目录为.next/static和.next/server/app（根据Next.js版本微调）。
  • 环境变量：在Static Web Apps的「配置」中添加NEXTAUTH_URL（设为你的Static Web Apps域名）等必要变量。

通用排查要点 #

• 环境变量校验：确保生产环境所需的所有变量（如数据库连接串、Next Auth密钥）均已正确配置，无遗漏或拼写错误。
• 日志定位问题：通过Azure对应服务的日志功能排查——比如App Service的「日志流」、Static Web Apps的「函数日志」，定位具体报错（如Next Auth认证请求失败、服务端组件渲染异常）。
• 版本兼容性：确保Azure服务的Node.js运行时版本不低于项目要求的最低版本，避免因版本差异导致的运行错误。

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