Vite 静态资源与媒体资产处理：图片、字体、SVG 与 Worker

public/ 下的文件：
  - 不进构建、不加 hash → 文件名变时要手动同步缓存策略
  - 无法 tree-shake、无法按需加载
  - 路径固定为 /xxx，适合 favicon、robots.txt、公开静态

import 的资源：
  - 生成内容 hash（img-3f4k2a.png）→ 缓存友好（immutable）
  - 可懒加载、可参与代码分割
  - 超过 assetsInlineLimit 才外链，否则内联

// 正确：业务资源用 import
import logo from "./assets/logo.png";
<img src={logo} alt="logo" />;

// 仅当确实要"绝对路径直出"才用 public/
// <img src="/logo.png" />

// vite.config.js
export default {
  build: {
    assetsInlineLimit: 4096,   // 4KB 以下内联
    assetsDir: "assets",       // 产物目录
  },
};

内联（data URI）：
  + 少一次 HTTP 请求
  - HTML/JS/CSS 变大、无法缓存、破坏 CSS/JS 的缓存命中
外链（独立文件）：
  + 可独立缓存（immutable hash）、可并发下载
  - 多一次请求

产物名带 hash（logo-a1b2c3.png）
→ 内容变了 hash 变 → 浏览器重新拉取
→ 内容没变 hash 不变 → 长缓存（immutable）

// 静态资源哈希在生产产物里的形态
// dist/assets/logo-a1b2c3d4e5.png

// vite-plugin-imagemin / vite-plugin-image-optimizer
import imageOptimizer from "vite-plugin-image-optimizer";
export default {
  plugins: [imageOptimizer({ png: { quality: 80 }, jpeg: { quality: 75 } })],
};

<img src={bigImg} loading="lazy" alt="" />

<img
  src={img}
  srcSet={`${img} 1x, ${img2x} 2x`}
  sizes="(max-width: 600px) 100vw, 50vw"
  alt=""
/>

<!-- 现代格式：AVIF/WebP 更小，回退 JPEG -->
<picture>
  <source srcSet="hero.avif" type="image/avif" />
  <source srcSet="hero.webp" type="image/webp" />
  <img src="hero.jpg" alt="hero" />
</picture>

@font-face {
  font-family: "MyFont";
  src: url("/fonts/my.woff2") format("woff2"),
       url("/fonts/my.woff") format("woff");
  font-display: swap;          /* 关键：文本先渲染、字体后换 */
}

// vite-plugin-subfont 或本地工具（glyphhanger/pyftsubset）
// 只保留常用中文 6763 常用字 / 页面实际用字

# pyftsubset 示例：保留 "前端构建" 等字
pyftsubset my.woff2 --text="前端构建Vite资源" --output-file=subset.woff2

swap     → 文本先显示系统字体，字体加载后替换（最常用，不阻塞）
block    → 白屏等待字体（FOUC 少但慢）
optional → 网络差就不等字体，用系统字体

<link rel="preload" href="/fonts/my.woff2" as="font" type="font/woff2" crossorigin />

import { ReactComponent as Logo } from "./logo.svg";
// 可传 color/className，随框架走
<Logo color="var(--primary)" className="logo" />;

<svg>
  <use href="/sprite.svg#icon-home"></use>
</svg>

- 静态图标（不改色）→ 外链或雪碧图
- 交互/改色图标 → vite-plugin-svgr 组件化
- 小批量图标 → 内联（省请求）

// 正确：Vite 会打包 worker 文件
const worker = new Worker(new URL("./my-worker.js", import.meta.url));

// worker 里也能用模块语法（type: "module"）
const worker = new Worker(new URL("./worker.ts", import.meta.url), {
  type: "module",
});

// 在 Worker 内加载 WASM（避免阻塞主线程）
// worker.ts
import wasmUrl from "./heavy.wasm?url";  // 拿到 WASM 的 URL
WebAssembly.instantiateStreaming(fetch(wasmUrl));

- new URL(x, import.meta.url) 是"相对当前模块"解析（不要写死路径）
- Worker 数量要节制：每个 Worker 是独立线程（内存、启动开销）
- 大量并行任务用 Worker 池（Pool），别逐任务开 Worker

// 动态 import Worker（按需、代码分割）
const { default: WorkerClass } = await import("./heavy.worker?worker");
const w = new WorkerClass();

// 静态已知 → import
import img from "./a.png";

// 运行时才知道的目录 → new URL + import.meta.url
const url = new URL(`./icons/${name}.png`, import.meta.url);

// 明确只要 URL（不要 Vite 处理内容）→ ?url 后缀
import assetUrl from "./file.pdf?url";

// ?raw：读文本内容（SVG 字符串、代码高亮源）
import svgStr from "./icon.svg?raw";

// ?inline：小资源强制内联
import tiny from "./dot.png?inline";

□ 业务资源全部 import（别堆 public/）
□ 小图标/小 SVG 内联，照片大图外链 + 懒加载
□ 图片已压缩、现代格式（WebP/AVIF）
□ 首屏图 ≤ 150KB、关键字体子集化 + preload + swap
□ SVG：交互图标组件化、静态图标雪碧/外链
□ Worker 走 Vite 原生加载、数量克制
□ 产物资产走 hash 缓存（内容变 hash 变）
□ 用 vite build --report 看最终体积

# 看产物与资产体积
npx vite build --report
du -sh dist/assets/

# 看 Vite 实际输出了哪些资产
ls dist/assets/
# 检查页面引用的资源 hash 与 dist 是否一致
grep -o 'assets/[^"]*' dist/index.html | head