GitHub Actions部署Node.js Azure App Service遇403/404错误求助

1. 部署路径与启动配置不匹配 #

Azure App Service默认从/home/site/wwwroot目录启动应用，如果GitHub Actions部署时未将核心文件传到对应位置，或启动命令未指向index.js，就会触发403/404错误：

• 打开GitHub Actions工作流文件（如.github/workflows/azure-webapps.yml），检查部署步骤的文件路径，确认index.js、public文件夹、package.json等核心文件都已上传到App Service根目录。
• 登录Azure门户进入App Service配置页，确认启动命令设置为node index.js；如果package.json里配置了start脚本（如"start": "node index.js"），也可设置为npm start。

2. 静态文件配置异常 #

本地能访问public/index.html但线上无法访问，大概率是Azure未正确识别静态文件目录：

• 先确认index.js中是否通过express.static('public')正确托管静态文件夹；若代码无问题，Windows环境的App Service需在项目根目录添加web.config文件配置路由：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <staticContent>
      <mimeMap fileExtension=".*" mimeType="application/octet-stream" />
    </staticContent>
    <rewrite>
      <rules>
        <rule name="Node.js" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          </conditions>
          <action type="Rewrite" url="index.js" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Linux环境的App Service无需web.config，但要确保Express的静态文件托管代码逻辑正确。

3. 部署文件缺失或缓存干扰 #

部署过程可能遗漏文件，或旧缓存残留导致异常：

• 在GitHub Actions的部署步骤后添加检查环节，用Azure CLI查看服务器文件：

- name: 检查部署文件
  uses: azure/CLI@v1
  with:
    inlineScript: |
      az webapp ssh --name 你的应用名 --resource-group 你的资源组 --command "ls -la /home/site/wwwroot"

确认index.js、public、node_modules等文件/文件夹存在。

• 清理GitHub Actions缓存，重新触发部署，避免旧依赖或文件干扰。

4. 应用日志无法查看的问题 #

启用日志后看不到应用输出，是因为日志配置未完全开启：

• 进入Azure门户的App Service > 监控 > 日志流，开启应用日志文件（文件系统）和Web服务器日志，并将日志级别设置为Info或Verbose。
• 在index.js的启动逻辑中添加日志输出，比如：

app.listen(process.env.PORT || 3000, () => {
  console.log(`服务器运行在端口 ${process.env.PORT || 3000}`);
});

如果日志流中看不到这条输出，说明应用根本未启动，需回到启动命令和文件路径的排查环节。

5. Node版本与依赖兼容性问题 #

更换Node版本后问题未解决，可能是依赖包存在兼容性冲突：

• 检查package.json的engines字段，指定当前使用的Node版本，比如：

"engines": {
  "node": "21.x"
}

确保App Service的运行时栈版本与此一致。

• 在GitHub Actions的部署流程中，添加npm install --production步骤，保证生产依赖正确安装。

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