请求提供MkDocs (Material)部署至Azure Web Apps的分步指南

前置准备 #

• 本地先确认MkDocs能正常构建：运行mkdocs build生成site文件夹，打开site/index.html验证内容、样式都正常显示。
• 确保你的Azure账号有权限创建Web App及相关资源，提前建好资源组。

方式一：手动部署静态文件（适合快速验证） #

1. 创建Azure Web App #

• 登录Azure门户，搜索「Web App」点击「创建」
• 填写基础信息：选择对应订阅、资源组，Web App名称要全局唯一；发布方式选「代码」，运行时栈选Python 3.11（后续启用静态网站功能后不影响）；其余配置按需选择，完成创建。

2. 启用静态网站功能 #

• 进入刚创建的Web App，左侧菜单找「配置」→「静态网站」
• 开启静态网站，设置「默认文档」为index.html，「404文档」为404.html，点击保存。
• 保存后页面会显示关联的存储账户及$web容器信息，记下来备用。

3. 上传静态文件 #

• 打开关联的存储账户，进入「容器」→「$web」
• 把本地site文件夹下的所有文件（包括子文件夹）上传到这里：可以直接拖拽，或者用AzCopy命令更高效：

  azcopy copy "./site/*" "https://<你的存储账户名>.blob.core.windows.net/$web" --recursive
  

• 替换命令里的<你的存储账户名>为实际名称。

4. 验证访问 #

• 打开Web App的默认域名（格式：https://<你的Web App名称>.azurewebsites.net），确认站点正常加载。

方式二：Azure DevOps自动构建部署（适合持续更新） #

1. 关联仓库与创建Pipeline #

• 登录Azure DevOps，创建新项目，关联你的GitHub仓库（授权后选择目标仓库即可）。
• 进入项目「Pipelines」→「创建流水线」，选择「GitHub」→ 选你的仓库 → 选「Starter pipeline」。

2. 配置Pipeline YAML #

• 替换默认的YAML内容为以下代码，注意替换占位符：

  trigger:
  - main # 替换成你的主分支名，比如master
  
  pool:
    vmImage: 'ubuntu-latest'
  
  steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.11'
      addToPath: true
  
  - script: |
      pip install mkdocs-material
      mkdocs build --clean
    displayName: '构建MkDocs站点'
  
  - task: AzureWebApp@1
    inputs:
      azureSubscription: '<你的Azure服务连接名>' # 提前在DevOps中创建好Azure服务连接
      appName: '<你的Web App名称>'
      package: '$(System.DefaultWorkingDirectory)/site'
      deploymentMethod: 'zipDeploy'
  

• 提前在Azure DevOps的「项目设置」→「服务连接」中创建Azure服务连接，关联你的Azure账号和目标资源组。

3. 运行Pipeline #

• 保存YAML文件，触发第一次构建部署，等待任务完成后，访问Web App域名验证站点。

常见问题排查 #

• 404错误：检查静态网站的默认文档是否设为index.html；手动部署时确认文件都传到$web容器根目录；CI/CD中确认package路径正确指向site文件夹。
• 样式/资源加载失败：检查mkdocs.yml中的site_url是否设置为Web App的域名；确保Web App启用了HTTPS，避免混合内容拦截。
• 构建失败：本地先运行mkdocs build确认无错误；检查Pipeline中的Python版本与本地一致；确认mkdocs-material安装命令正确。

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