Node.js应用部署至Azure Web App失败求助及相关疑问

我来帮你排查这个部署问题，顺便把Azure里npm install的触发逻辑说清楚——毕竟你本地能正常跑，大概率是部署环境的配置或路径解析出了问题。

一、先搞定部署失败的核心问题 #

你的start脚本指向node_modules里的文件本身没问题，但Azure的IISNode配置和本地Node环境的路径解析有几个要注意的细节：

1. 手动配置web.config的正确姿势 #

你修改了Rewrite规则的URL，但可能漏掉了handlers部分的配置。正确的web.config需要同时更新handler的路径和Rewrite规则的URL，示例如下：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <!-- 这里要改成你的入口文件路径 -->
      <add name="iisnode" path="./node_modules/@samplescope/samplefolder/sample_service.js" verb="*" modules="iisnode"/>
    </handlers>
    <rewrite>
      <rules>
        <rule name="NodeInspector" patternSyntax="ECMAScript" stopProcessing="true">
          <match url="^./node_modules/@samplescope/samplefolder/sample_service.js\/debug[\/]?" />
        </rule>
        <rule name="StaticContent">
          <action type="Rewrite" url="public{REQUEST_URI}" />
        </rule>
        <rule name="DynamicContent">
          <conditions>
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="True" />
          </conditions>
          <!-- 这里也要对应你的入口文件 -->
          <action type="Rewrite" url="./node_modules/@samplescope/samplefolder/sample_service.js" />
        </rule>
      </rules>
    </rewrite>
    <iisnode nodeProcessCommandLine="&quot;%programfiles%\nodejs\%WEBSITE_NODE_DEFAULT_VERSION%\node.exe&quot;" />
  </system.webServer>
</configuration>

注意：路径是相对于Azure应用根目录D:\home\site\wwwroot的，你的相对路径写法没问题，但必须保证handlers和rewrite规则里的路径完全一致。

2. 让Kudu自动生成web.config的技巧 #

如果不想手动写web.config，你可以在package.json里加一个main字段指向入口文件，帮助Kudu正确识别：

{
  "main": "./node_modules/@samplescope/samplefolder/sample_service.js",
  "scripts": {
    "start": "node ./node_modules/@samplescope/samplefolder/sample_service.js"
  }
}

Kudu生成配置时会优先参考main字段，其次才是start脚本。另外要确保Azure门户「配置」→「常规设置」里的启动命令是空的，这样应用会自动用package.json的start脚本启动。

3. 关键排查步骤 #

• 去Azure门户「部署中心」→「日志」查看部署过程，确认npm install是否成功，有没有依赖安装失败的报错；
• 打开「监控」→「日志流」，查看应用启动时的具体错误（比如找不到文件、端口占用等）；
• 进入Kudu控制台（https://<你的应用名>.scm.azurewebsites.net/DebugConsole），手动执行npm start，如果这里能正常启动，说明是配置问题；如果不能，就是环境依赖或文件权限的问题。

二、Azure Web App中npm install的触发机制 #

npm install的触发完全取决于你的部署方式：

• 自动触发的场景：当你用Git部署、Zip部署（启用「构建部署」选项）、GitHub Actions或Azure DevOps部署时，Kudu（Azure的部署引擎）会自动检测package.json，然后执行npm install。默认是生产环境模式（npm install --production），如果需要安装dev依赖，可以设置环境变量NPM_CONFIG_PRODUCTION=false；
• 不会自动触发的场景：如果是用Zip部署但关闭了「构建部署」，或者直接用FTP上传文件，Kudu不会执行npm install。这时候你需要本地装好所有依赖，把node_modules一起上传，或者手动在Kudu控制台执行npm install；
• 禁用自动构建：如果你想完全自己控制依赖，可以设置环境变量SCM_DO_BUILD_DURING_DEPLOYMENT=false，但一般不推荐，除非你有特殊需求。

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