Vite 构建缓存与持久化缓存策略：依赖预构建、Rollup 缓存与 CI 加速

第一层（.vite/deps）：npm 依赖被预构建成优化后的 ESM → 启动秒开
第二层（.cache）：单文件转译（TS/JSX）缓存 → 热更新快
第三层（内存）：模块依赖图 → dev server 会话内复用

- CJS 依赖（老 npm 包）转成 ESM
- 上千个模块的依赖打散成少量 chunk → 浏览器请求数骤降
- 不透明依赖的转换成本一次付清，之后命中缓存

ls node_modules/.vite/deps      # 预构建产物
ls node_modules/.cache/vite     # 转换缓存

- 扫描 import 的裸模块（react、lodash...）
- 用 esbuild 把 CJS → ESM、合并散装模块
- 产物带 hash：deps/react.js + hash 文件

失效（重新预构建）当：
  - package.json / lockfile 变化
  - optimizeDeps.include/exclude 配置变化
  - Vite 版本变化
  - 手动 --force（强制重新优化）
命中（直接用旧产物）当：
  - 依赖集合与配置都没变

npx vite --force        # 强制重新预构建（改依赖后保险）
npx vite optimize       # 手动预构建（提前做，而非首次访问触发）

// vite.config.js：显式声明要预构建的依赖
export default {
  optimizeDeps: {
    include: ["lodash-es", "axios"],
    exclude: ["@your-lib/private"],   // 已有 ESM 的不需要预构建
  },
};

- 依赖预构建：package.json + lockfile 的 hash
- 转换缓存：源码文件内容 hash
- 配置缓存：vite.config 的 hash

- lockfile 有换行/排序抖动 → hash 变 → 全量重来
- 缓存目录被 CI 清理策略删除
- 切了 Node 版本 → 二进制缓存不兼容
- 缓存 key 没把"平台"算进去（CI 缓存跨 OS）

- 默认每次都重新执行"转换 + 打包"
- 没有 webpack 那样的持久化构建缓存（disk cache）
- 要增量/缓存构建 → 靠外部缓存（第 5、6 节）或换工具

dev 缓存的产物（.vite）与 build 无关 → build 不会复用 dev 的预构建
build 有自己的依赖处理（Rollup 处理 node_modules）
→ 别指望"我 dev 跑过 build 就快"

① 缓存依赖安装（node_modules 持久化）→ 装依赖秒回
② 缓存预构建产物（.vite）→ 冷启动依赖优化跳过
③ 用支持增量/缓存的替代（Turbopack 正在做持久缓存）

- name: 缓存 node_modules
  uses: actions/cache@v4
  with:
    path: node_modules
    key: deps-${{ hashFiles('pnpm-lock.yaml') }}

- name: 缓存 Vite deps
  uses: actions/cache@v4
  with:
    path: node_modules/.vite
    key: vite-deps-${{ hashFiles('pnpm-lock.yaml') }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4

      - name: 缓存依赖（node_modules）
        uses: actions/cache@v4
        with:
          path: |
            node_modules
            node_modules/.vite
          key: ${{ runner.os }}-deps-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-deps-

      - name: 安装依赖
        run: pnpm install --frozen-lockfile

      - name: 构建
        run: pnpm build

key: ${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
restore-keys: 上一级通配 → lockfile 微变也能复用旧缓存大部分

- lockfile 保持稳定（别让无关提交动它）
- 把 node_modules 与 .vite 分开缓存（一个失效不影响另一个）
- 平台入 key（linux/darwin/win 分开）
- 缓存上限管理：大缓存要定期清（prune）

- name: 检查缓存命中
  run: test -d node_modules/.vite/deps && echo "vite cache HIT" || echo "vite cache MISS"

- 仓库体积爆炸（.vite 有依赖的优化产物）
- 跨平台产物提交 → CI 上"命中奇怪错误"（平台差异）
- 缓存随仓库历史锁定 → 失效逻辑错乱
- PR 噪声：每次依赖变化 diff 一堆二进制

git ls-files | grep -E '\.vite|\.cache' | head
# 若有输出 → 从 Git 移除
git rm -r --cached node_modules/.vite

# 强制重新预构建（先试这个）
npx vite --force

# 手动清缓存
rm -rf node_modules/.vite node_modules/.cache

# 查看预构建产物时间戳是否最新
ls -lt node_modules/.vite/deps | head

# 构建时打印缓存相关日志（-d 调试）
npx vite build -d

□ .gitignore 已排除 .vite/.cache/dist
□ CI 缓存：node_modules 与 .vite 分开、key 含 lockfile + 平台
□ restore-keys 兜底（lockfile 微变可复用）
□ 改依赖后 --force 重新预构建（本地）
□ optimizeDeps.include 声明关键依赖（减少首访卡顿）
□ lockfile 稳定（避免缓存 key 抖动全量重来）
□ 生产 build 期望管理好（Vite 无持久缓存，靠 CI 补）
□ 定期检查缓存命中率（CI 日志）