如何设置Azure WebApp默认文档为子目录端点及解决CLI与门户差异

正确设置默认文档的方法 #

方法1：修正Azure CLI命令 #

你之前的命令里路径用了反斜杠\，Azure WebApp的路径识别需要用正斜杠/，而且要确保命令格式正确。正确的CLI命令如下：

az webapp update -g [resourceGroup] -n [appname] --add siteConfig.defaultDocuments "swagger/index.html"

如果需要覆盖原有默认文档列表（而非追加），可以用--set重置整个数组：

az webapp update -g [resourceGroup] -n [appname] --set siteConfig.defaultDocuments="index.html,swagger/index.html"

（保留index.html是为了兼容原有默认访问需求，不需要的话可以只留swagger/index.html）

方法2：通过web.config配置（适用于ASP.NET WebAPI） #

如果你的WebAPI是ASP.NET项目，直接在项目根目录的web.config中添加默认文档配置，部署后会自动生效：

<system.webServer>
  <defaultDocument enabled="true">
    <files>
      <add value="swagger/index.html" />
      <add value="index.html" />
    </files>
  </defaultDocument>
</system.webServer>

这种方式更直接，也不会出现CLI与门户的显示差异问题。

门户与Azure CLI显示差异的原因 #

1. 路径格式解析问题：你之前用了反斜杠swagger\index.html，CLI执行时会把反斜杠识别为转义字符，导致配置未被正确序列化到siteConfig中，所以az webapp show返回null；但Azure门户会自动修正路径分隔符，因此能正常显示并生效。
2. API返回的序列化差异：Azure门户和az webapp show调用的API逻辑不同，门户读取的是实际生效的运行时配置，而CLI的show命令有时无法正确返回嵌套数组类型的配置（比如defaultDocuments），尤其是数组仅含一个元素时，可能被解析为null。
3. 缓存延迟：CLI的本地缓存或Azure API的缓存可能导致az webapp show未及时获取最新配置，而门户会实时读取运行时的配置状态。

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