# html-cache-fix

**Repository Path**: miikio/html-cache-fix

## Basic Information

- **Project Name**: html-cache-fix
- **Description**: HTML资源缓存修复。适用于HTML资源被强缓存情况下的纯前端修复方式（如微信/企业微信浏览器中的页面缓存）。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-21
- **Last Updated**: 2025-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

## 项目主页
[https://gitee.com/miikio/html-cache-fix](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 字符集](https://www.iana.org/assignments/character-sets) |
  | `assetsDir` | String | `'dist'` | 资源文件夹路径。（资源列表存在项时表示其默认值） |
  | `sourcePath` | String | `'index.html'` | [AssetOptions.sourcePath](#AssetOptions.sourcePath) |
  | `targetPath` | String | `'index-source.html'` | [AssetOptions.targetPath](#AssetOptions.targetPath) |
  | `referPath` | String | -- | [AssetOptions.referPath](#AssetOptions.referPath) |
  | `assetsList` | [AssetOptions\[\]](#AssetOptions) | -- | 资源列表 |

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

## 安装依赖
```bash
# npm
npm install html-cache-fix -D

# yarn
yar add html-cache-fix -D

# pnpm
pnpm add html-cache-fix -D
```

## 命令行使用示例
```bash
# 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 使用示例
```js
// ./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'
    }
  ]
})
```
```bash
# 使用 node 执行示例文件
node ./demo.js
```

## Vite 插件示例
```js
// 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 插件示例
```js
// webpack.config.js
const { webpackPlugin: HtmlCacheFix } = require('html-cache-fix')

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

## Vue Cli 插件示例
```js
// 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({ /* ... */ }))
  }
}
```