如何将VitePress部署到Azure静态Web应用并配置Base URL？

数据老陈

2026-7-24

解决VitePress部署到Azure静态Web应用的路径匹配问题

问题根源

你设置VitePress的base: '/web/myapp'后，构建产物里的资源引用路径都是/web/myapp/assets/xxx，但Azure静态Web应用把docs/.vitepress/dist作为部署根目录，实际资源存放在根目录的/assets下，导致页面请求/web/myapp/assets/xxx时返回404。

解决方案

提供两种可行的解决思路：

方法一：调整VitePress构建输出结构，匹配Azure部署路径

修改VitePress配置文件（docs/.vitepress/config.js），指定构建输出目录为../dist/web/myapp，让产物自动生成web/myapp子目录：

export default {
  base: '/web/myapp/',
  build: {
    outDir: '../dist/web/myapp'
  }
}

重新执行本地构建命令npm run docs:build，此时docs/dist/web/myapp目录下会包含index.html和assets文件夹。
更新Azure静态Web应用的配置：

app_location: "docs/dist/web/myapp"
skip_app_build: true

这样Azure会把web/myapp目录下的内容作为部署根，访问http://xxxxx/web/myapp/index.html时，资源路径/web/myapp/assets/xxx会对应到部署目录下的assets文件夹，加载正常。

方法二：通过Azure路由配置映射路径

如果不想调整构建输出结构，可以通过Azure静态Web应用的路由规则来适配路径：

在docs/.vitepress/dist目录下创建staticwebapp.config.json文件，添加路由映射规则：

{
  "routes": [
    // 把/web/myapp下的所有资源请求映射到根目录对应路径
    {
      "route": "/web/myapp/*",
      "serve": "/{path}"
    },
    // 处理根路径跳转
    {
      "route": "/web/myapp",
      "serve": "/index.html"
    }
  ]
}