部署Vite+React应用至Azure WebApps时遭遇RSYNC错误

问题背景 #

使用Vite React模板开发的应用，首次部署到Azure WebApp正常，但二次及后续部署时出现RSYNC错误：

rsync: [receiver] rename "/home/site/wwwroot/dist/.index.html.qY0R0W" -> "dist/index.html": No such file or directory (2)
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1338) [sender=3.2.7]

已启用代码拆分控制构建文件大小，但问题仍存在，目前只能通过删除重建WebApp解决。

可能的原因及解决办法 #

1. 目标目录权限异常 #

RSYNC重命名失败大概率是/home/site/wwwroot/dist目录的权限问题，首次部署后权限可能被变更或锁定。

• 通过Azure门户的SSH登录到WebApp实例，执行命令查看权限：

  ls -l /home/site/wwwroot/dist
  

• 若权限不符合部署用户的读写要求，执行权限修复：

  sudo chmod -R 755 /home/site/wwwroot/dist
  sudo chown -R www-data:www-data /home/site/wwwroot/dist
  

2. 禁用node_modules缓存 #

Azure WebApp默认缓存node_modules以加速部署，但缓存过程可能导致文件锁定，干扰RSYNC操作：

• GitHub Actions部署：在部署步骤中添加环境变量禁用缓存：

  - name: Deploy to Azure Web App
    uses: azure/webapps-deploy@v2
    with:
      app-name: '<your-app-name>'
      slot-name: 'production'
      package: '.'
    env:
      NODE_MODULES_CACHE: false
  

• VS Code部署：在Azure扩展设置中关闭Node Modules Cache选项；
• WebApp应用设置：添加应用配置项NODE_MODULES_CACHE=false。

3. 避免运行时文件锁定 #

WebApp运行时可能锁定dist目录下的静态文件（如index.html、js资源），导致RSYNC无法重命名临时文件：

• 部署前先停止WebApp，完成后再启动：
  • GitHub Actions中加入Azure CLI命令：

    - name: Stop Web App
      run: az webapp stop --name <your-app-name> --resource-group <your-rg-name>
    - name: Deploy to Azure Web App
      uses: azure/webapps-deploy@v2
      # ... 部署配置
    - name: Start Web App
      run: az webapp start --name <your-app-name> --resource-group <your-rg-name>
    

• VS Code部署时，手动在Azure门户停止WebApp后再执行部署。

4. 修改构建输出路径或部署策略 #

更换Vite构建的输出目录，避免直接覆盖原dist目录：

• 在vite.config.js中修改输出目录：

  export default defineConfig({
    build: {
      outDir: 'build'
    }
  })
  

• 部署时同步build目录而非dist，绕过原目录的潜在锁定问题。

5. 切换部署方式（绕过RSYNC） #

若RSYNC问题持续，改用Zip Deploy或Static Web Apps部署：

• Zip Deploy：将构建后的文件打包为zip，执行命令部署：

  zip -r dist.zip dist/
  az webapp deployment source config-zip --resource-group <your-rg-name> --name <your-app-name> --src dist.zip
  

• Azure Static Web Apps：若应用为纯静态前端，直接部署到Static Web Apps，无需依赖WebApp的RSYNC机制。

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