html-cache-fix

html-cache-fix (HTML资源缓存修复)

项目主页

https://gitee.com/miikio/html-cache-fix

项目简介

• 版本： 0.1.0
• 更新时间： 2025.4.21
• 定位：修复工具, 脚手架插件
• 介绍：适用于HTML资源被强缓存情况下的纯前端修复方式（如微信/企业微信浏览器中的页面缓存）。
• 原理：在被缓存的页面中使用无缓存方式请求原始资源，并覆盖导航到当前页面。

参数说明

• Options 配置项：

  名称	类型	默认值	释义
  mode	String	'ajax'	修复模式。可选值：( 'ajax' | 'jsonp' )
  crossOrigin	Boolean	false	使用同源策略请求 (仅 jsonp 模式可用，ajax 模式下固定为 true)
  charsetFix	String | Boolean	'utf-8'	字符集修复 (自动为源文件的 script 标签添加字符集声明)。可选值请参考 IANA 字符集
  assetsDir	String	'dist'	资源文件夹路径。（资源列表存在项时表示其默认值）
  sourcePath	String	'index.html'	AssetOptions.sourcePath
  targetPath	String	'index-source.html'	AssetOptions.targetPath
  referPath	String	--	AssetOptions.referPath
  assetsList	AssetOptions[]	--	资源列表

• AssetOptions 资源配置项：

  名称	类型	默认值	释义
  assetsDir	String	'dist'	资源文件夹路径
  sourcePath	String	'index.html'	原始文件路径 (资源文件夹下的相对路径)
  targetPath	String	'index-source.html'	映射文件路径 (资源文件夹下的相对路径。默认值为原始文件名后缀添加 '-source')
  referPath	String	--	资源引用路径 (生成的原始文件引用映射文件的绝对/相对路径，与应用部署路径相关)

安装依赖

# npm
npm install html-cache-fix -D

# yarn
yar add html-cache-fix -D

# pnpm
pnpm add html-cache-fix -D

命令行使用示例

# use default options
npm run html-cache-fix

# use custom options
npm run html-cache-fix mode="ajax" assetsDir="dist/" sourcePath="index.html" targetPath="refer/index.html" referPath="/refer/index.html"

Api 使用示例

// ./demo.js
import HtmlCacheFix from 'html-cache-fix'

// 单个文件修复
HtmlCacheFix({
  mode: 'ajax',
  charsetFix: 'utf-8',
  assetsDir: 'dist',
  sourcePath: 'index.html',
  targetPath: 'refer/index.html',
  referPath: '/refer/index.html'
})

// 多个文件修复
HtmlCacheFix({
  mode: 'jsonp',
  crossOrigin: true,
  charsetFix: 'utf-8',
  assetsDir: 'dist',
  assetsList: [
    {
      sourcePath: 'index-a.html',
      targetPath: 'refer/index-a.html',
      referPath: '/refer/index-a.html'
    },
    {
      sourcePath: 'index-b.html',
      targetPath: 'refer/index-b.html',
      referPath: '/refer/index-b.html'
    },
    {
      assetsDir: 'dist-ots', // 未设置时默认使用 Options.assetsDir
      sourcePath: 'index-ots.html',
      targetPath: 'refer/index-ots.html',
      referPath: '/refer/index-ots.html'
    }
  ]
})

# 使用 node 执行示例文件
node ./demo.js

Vite 插件示例

// vite.config.js
import path from 'node:path'
import { defineConfig } from 'vite'
import { vitePlugin as HtmlCacheFix } from 'html-cache-fix'

export default defineConfig({
  /* ...other config */
  plugins: [
    HtmlCacheFix({
      mode: 'ajax',
      assetsDir: path.resolve(process.cwd(), 'dist'),
      sourcePath: 'index.html',
      targetPath: 'index-source.html'
    })
  ]
})

Webpack 插件示例

// webpack.config.js
const { webpackPlugin: HtmlCacheFix } = require('html-cache-fix')

module.exports = {
  /* ...other config */
  plugins: [
    new HtmlCacheFix({ /* ... */ })
  ]
}

Vue Cli 插件示例

// vue.config.js
const { webpackPlugin: HtmlCacheFix } = require('html-cache-fix')

module.exports = {
  /* ...other config */
  configureWebpack: {
    plugins: [
      new HtmlCacheFix({ /* ... */ })
    ]
  },
  // or define function
  configureWebpack: (config) => {
    config.plugins.push(new HtmlCacheFix({ /* ... */ }))
  }
}