如何在Vite构建产物中为资源添加版本查询后缀？

一、给打包生成的JS/CSS资源自动加版本参数 #

Vite结合Rollup配置，可以直接给构建生成的资源文件添加版本查询字符串：

在vite.config.js中配置如下：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// 版本号可自定义，也可从package.json或Git哈希动态获取
const VERSION = '1.0.0'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        // 给JS chunk文件加版本参数
        chunkFileNames: `assets/[name]-[hash].js?v=${VERSION}`,
        // 给入口JS文件加版本参数
        entryFileNames: `assets/[name]-[hash].js?v=${VERSION}`,
        // 给CSS、图片、字体等静态资源加版本参数
        assetFileNames: `assets/[name]-[hash].[ext]?v=${VERSION}`
      }
    }
  }
})

配置后，Vite打包生成的所有编译产物都会自动带上?v=VERSION后缀。

二、处理index.html中的手动引入资源 #

上面的配置仅处理Vite编译生成的资源，对于index.html中手动写入的favicon.ico、manifest.webmanifest、registerSW.js等静态资源，需要通过Vite的钩子来修改：

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

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

const VERSION = '1.0.0'

export default defineConfig({
  plugins: [
    react(),
    {
      name: 'html-resource-version',
      transformIndexHtml(html) {
        // 匹配所有不带查询参数的href/src属性，添加版本后缀
        return html.replace(
          /(href|src)="([^"?]+)(?=")/g,
          `$1="$2?v=${VERSION}"`
        )
      }
    }
  ],
  // 保留之前的build配置
  build: { /* ... */ }
})

如果需要精准匹配特定后缀的资源，可修改正则为：

/(href|src)="([^"?]+\.(ico|webmanifest|js|png|jpg))(?=")/g

三、处理CSS中的图片URL引用 #

要给CSS里background-image:url()这类路径加版本参数，可通过PostCSS实现：

方式1：使用postcss-url插件 #

1. 安装依赖：

npm install postcss-url --save-dev

2. 项目根目录创建postcss.config.js：

const VERSION = '1.0.0'

export default {
  plugins: [
    require('postcss-url')({
      url: (asset) => {
        // 给图片资源添加版本参数
        if (['.png', '.jpg', '.svg', '.gif'].some(ext => asset.url.includes(ext))) {
          return `${asset.url}?v=${VERSION}`
        }
        return asset.url
      }
    })
  ]
}

方式2：自定义PostCSS插件（无需额外依赖） #

直接在postcss.config.js中写简单插件：

const VERSION = '1.0.0'

export default {
  plugins: [
    {
      postcssPlugin: 'css-resource-version',
      Declaration(decl) {
        // 匹配包含url()的CSS属性，添加版本后缀
        if (decl.value.includes('url(')) {
          decl.value = decl.value.replace(
            /url\("?([^"?]+)"?\)/g,
            `url("$1?v=${VERSION}")`
          )
        }
      }
    }
  ]
}

四、动态版本号（可选） #

如果不想手动维护版本号，可通过以下方式自动生成：

• 从package.json读取版本：

import pkg from './package.json' assert { type: 'json' }
const VERSION = pkg.version

• 使用Git提交哈希作为版本：

import { execSync } from 'child_process'
const VERSION = execSync('git rev-parse --short HEAD').toString().trim()

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