通过GitHub Actions部署Next.js到Azure Web App遇模块缺失错误

错误日志 #

Error: Cannot find module '../server/require-hook'
Require stack:
- /home/site/wwwroot/node_modules/.bin/next
    at Module._resolveFilename (node:internal/modules/cjs/loader:1145:15)
    at Module._load (node:internal/modules/cjs/loader:986:27)
    at Module.require (node:internal/modules/cjs/loader:1233:19)
    at Module.patchedRequire (/agents/nodejs/node_modules/diagnostic-channel/dist/src/patchRequire.js:16:46)
    at Hook._require.Module.require (/agents/nodejs/node_modules/require-in-the-middle/index.js:167:34)
    at require (node:internal/modules/helpers:179:18)
    at Object.<anonymous> (/home/site/wwwroot/node_modules/.bin/next:6:1)
    at Module._compile (node:internal/modules/cjs/loader:1358:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1416:10)
    at Module.load (node:internal/modules/cjs/loader:1208:32) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/home/site/wwwroot/node_modules/.bin/next' ]
}

当前GitHub Actions配置 #

# Docs for the Azure Web Apps Deploy action: https://github.com/Azure/webapps-deploy
# More GitHub Actions for Azure: https://github.com/Azure/actions

name: Build and deploy Node.js app to Azure Web App - nextjs-az-template

on:
  push:
    branches:
      - master
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js version
        uses: actions/setup-node@v3
        with:
          node-version: '20.x'

      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present
          npm run test --if-present

      - name: Zip artifact for deployment
        run: zip release.zip ./* -r

      - name: Upload artifact for deployment job
        uses: actions/upload-artifact@v4
        with:
          name: node-app
          path: release.zip

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: 'Production'
      url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
    
    steps:
      - name: Download artifact from build job
        uses: actions/download-artifact@v4
        with:
          name: node-app

      - name: Unzip artifact for deployment
        run: unzip release.zip
      
      - name: 'Deploy to Azure Web App'
        id: deploy-to-webapp
        uses: azure/webapps-deploy@v3
        with:
          app-name: 'nextjs-az-template'
          slot-name: 'Production'
          package: .
          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_FB5C5356BD1A48A79DF07D1243712E42 }}

问题原因 #

错误源于GitHub Runner环境下打包的node_modules与Azure Web App运行环境不兼容，或是打包过程中Next.js依赖的文件路径出现异常。VSCode Azure扩展部署正常是因为它默认采用了更适配的部署逻辑，比如仅上传必要文件而非完整的node_modules。

解决方法 #

方案一：仅打包部署必需文件（推荐） #

修改Build阶段步骤，只收集Next.js部署核心文件，避免上传GitHub Runner环境下的node_modules：

1. 更新Build阶段脚本，替换原有打包步骤：

# 替换原有的"Zip artifact for deployment"步骤
- name: Prepare deployment files
  run: |
    mkdir deploy
    # 复制Next.js构建产物、配置文件和依赖清单
    cp -r .next/ deploy/
    cp package.json deploy/
    cp package-lock.json deploy/
    [ -f next.config.js ] && cp next.config.js deploy/
    [ -d public/ ] && cp -r public/ deploy/
- name: Zip artifact for deployment
  run: zip -r release.zip deploy/

2. 更新Deploy阶段的部署路径，指向解压后的deploy目录：

- name: Unzip artifact for deployment
  run: unzip release.zip
- name: 'Deploy to Azure Web App'
  id: deploy-to-webapp
  uses: azure/webapps-deploy@v3
  with:
    app-name: 'nextjs-az-template'
    slot-name: 'Production'
    package: ./deploy
    publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_FB5C5356BD1A48A79DF07D1243712E42 }}

Azure Web App会自动根据package.json安装适配环境的依赖，避免路径和兼容性问题。

方案二：在Azure上重新安装生产依赖 #

若需保留原有打包逻辑，可在Deploy阶段移除上传的node_modules并重新安装适配环境的依赖：

1. 修改Build阶段的打包命令，排除node_modules：

- name: Zip artifact for deployment
  run: zip -r release.zip ./* -x "node_modules/*"

2. 在Deploy阶段添加依赖安装步骤：

- name: Unzip artifact for deployment
  run: unzip release.zip
- name: Install production dependencies
  run: npm install --production
- name: 'Deploy to Azure Web App'
  id: deploy-to-webapp
  uses: azure/webapps-deploy@v3
  with:
    app-name: 'nextjs-az-template'
    slot-name: 'Production'
    package: .
    publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_FB5C5356BD1A48A79DF07D1243712E42 }}

额外检查 #

确保package.json中的start脚本正确配置为：

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

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