如何在Vite+Vue的PWA manifest.json中用相对路径避免多环境重复配置

问题出在部署环境的**基础路径（base path）**和本地不一致，导致根路径/指向域名根而非应用根目录，进而让start_url和图标路径失效。不用维护多份manifest，下面是两种靠谱的解决方案：

方案一：用vite-plugin-pwa插件（推荐） #

这是Vite生态中专门处理PWA的插件，能自动适配Vite的base配置，无需手动修改路径。

步骤： #

1. 安装插件：

npm install vite-plugin-pwa -D

2. 修改vite.config.js：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    vue(),
    VitePWA({
      // 这里直接写manifest的基础配置
      manifest: {
        name: 'My app',
        short_name: 'My app',
        start_url: '/', // 插件会自动加上base路径
        display: 'standalone',
        background_color: '#ffffff',
        theme_color: '#ffffff',
        icons: [
          {
            src: 'img/pwa_logo.png', // 相对路径，插件自动拼接base
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      registerType: 'autoUpdate' // 可选，控制PWA更新逻辑
    })
  ],
  // 根据环境设置base路径：本地开发用根路径，生产环境设为部署的子路径
  base: process.env.NODE_ENV === 'production' ? '/your-deploy-subpath/' : '/'
})

原理： #

插件会读取Vite的base配置，自动将start_url和图标src拼接成正确的绝对路径，不管你部署在根目录还是子目录，都能正常识别。

方案二：手动动态生成Manifest（无需额外插件） #

如果不想用插件，可以通过模板+Vite构建钩子来动态替换路径。

步骤： #

1. 创建manifest.template.json模板文件：

{
    "name": "My app",
    "short_name": "My app",
    "start_url": "{{BASE_URL}}",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#ffffff",
    "icons": [
        {
            "src": "{{BASE_URL}}img/pwa_logo.png",
            "sizes": "512x512"
        }
    ]
}

2. 修改vite.config.js添加自定义插件：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import fs from 'fs'
import path from 'path'

export default defineConfig({
  plugins: [
    vue(),
    {
      name: 'dynamic-manifest',
      // 构建结束后生成最终的manifest.json
      buildEnd() {
        // 从环境变量取base路径，默认用根路径
        const baseUrl = process.env.VITE_BASE_URL || '/'
        const templatePath = path.resolve(__dirname, 'manifest.template.json')
        const outputPath = path.resolve(__dirname, 'dist/manifest.json')
        
        // 读取模板并替换占位符
        const templateContent = fs.readFileSync(templatePath, 'utf-8')
        const finalManifest = templateContent.replace(/{{BASE_URL}}/g, baseUrl)
        
        fs.writeFileSync(outputPath, finalManifest)
      }
    }
  ],
  base: process.env.VITE_BASE_URL || '/'
})

3. 在生产环境的.env.production文件中配置基础路径：

VITE_BASE_URL=/your-deploy-subpath/

关键注意点 #

• 部署前一定要确认base配置和实际部署路径一致（比如部署在https://example.com/my-app/，base就设为/my-app/）。
• 图标文件要放在Vite的public目录下（比如public/img/pwa_logo.png），这样构建时会被正确复制到dist目录。

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