@hzab/vite-config 0.0.2-alpha.0

package/docs/vite-pnpm-integration.md

@@ -0,0 +1,279 @@
+# Vite + pnpm 接入问题排查手册
+
+> 适用范围：pnpm 安装、Vite 7+/8（rolldown）开发的 Web 项目，尤其是大量使用 `@hzab/*` 系列包（这些包 `main` 指向 `src`，以源码形式被 Vite 直接编译）且依赖较多旧 CJS 包的项目。
+> 本文记录接入过程中高频踩坑的**现象 → 根因 → 诊断 → 修复**，供其他项目复用。
+
+---
+
+## 0. 一句话总纲
+
+**绝大多数报错都指向同一个根因：pnpm 的隔离布局不会把「传递依赖」提升到顶层 `node_modules`，导致 Vite 的依赖预构建（optimizeDeps）发现不了它们，只能按原始 CJS 文件裸供浏览器。**
+
+于是：
+
+- 裸供 CJS → `Uncaught ReferenceError: module is not defined`（文件里先出现 `module.exports`）
+- 裸供 CJS → `Uncaught ReferenceError: require is not defined`（文件里先出现 `require(...)`，如 es-shims 家族）
+- 裸供带顶层 `this` 的 UMD（`(function(global){ ... }(this,...))`）→ `Cannot set properties of undefined (setting 'X')`
+- CJS barrel 具名导出在预构建时静态识别不出 → `does not provide an export named 'X'`
+- 构建期老 IE hack → LightningCSS 报 `star property hack`
+- React Compiler 默认开启却缺包 → `Cannot find package 'babel-plugin-react-compiler'`
+
+---
+
+## 1. 常见症状与根因
+
+| 报错                                                                      | 阶段        | 根因                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `module is not defined`                                                   | dev         | 包是 CJS-only 且未被提升，Vite 未预构建，`module.exports = require(...)` 直接下发给浏览器                                                                                                                                                                                                                                                                 |
+| `require is not defined`                                                  | dev         | 同「module is not defined」一类的 CJS 裸供，只是文件内**先命中 `require(...)`**。常见于 es-shims 家族（`object-keys`、`regexp.prototype.flags`、`define-properties` 等）——它们是某个**被 `viteCommonjs.include` 转换的入口包**（如 `deep-equal`、`geojson-equality`）的依赖，入口包被转换后 `require('...')` 变成真实 import，其 CJS 依赖便被逐个独立裸供 |
+| `does not provide an export named 'X'`                                    | dev         | 包只有 CJS 构建，其用 `__exportStar`/`module.exports = {...}` 重导出的具名导出在预构建时被优化器丢掉                                                                                                                                                                                                                                                      |
+| `Cannot set properties of undefined (setting 'quickselect')`              | dev         | 包是 UMD（顶层 `this` 当全局对象）且未被预构建、未提升，Vite 按原始 ESM 裸供，ESM 严格模式下顶层 `this === undefined`                                                                                                                                                                                                                                     |
+| `Failed to resolve dependency: X, present in optimizeDeps.include`        | dev         | 包不可从项目根解析（没有顶层 `node_modules/X`），所以 `optimizeDeps.include` 里写了也解析不到                                                                                                                                                                                                                                                             |
+| `[lightningcss minify] Unexpected token Semicolon` / `star property hack` | build       | 旧 CSS 里的 IE hack（`*zoom`、`*display`、`*width`）被 LightningCSS 当作语法错误                                                                                                                                                                                                                                                                          |
+| `Cannot find package 'babel-plugin-react-compiler'`                       | build       | `@hzab/vite-config` 默认 `reactCompiler: "build-only"`，build 时加载 React Compiler preset 但包未安装                                                                                                                                                                                                                                                     |
+| `process is not defined`（`ReferenceError`）                              | dev + build | webpack 会 polyfill 全局 `process` 并经 DefinePlugin 注入 `process.env.*`；Vite 默认只替换 `process.env.NODE_ENV`，其余 `process.env.*` 在浏览器端原样残留；且 `optimizeDeps` 预构建产物**不经过** `define`                                                                                                                                               |
+
+---
+
+## 2. 判断「是否被预构建 / 是否被提升」的快速方法
+
+在项目根目录执行：
+
+```bash
+# 1) 包是否在顶层 node_modules？（没有 = 被 pnpm 隔离，Vite 大概率发现不了）
+dir node_modules\react-is        # Windows
+# ls node_modules/react-is       # macOS / Linux
+
+# 2) 从项目根能否用 node 解析到？（决定 optimizeDeps.include 是否可用）
+node -e "console.log(require.resolve('react-is'))"
+
+# 3) 该包在 .pnpm 里是否带 ESM 构建（esm/ 或 module 字段）？
+dir node_modules\.pnpm\react-is@*\node_modules\react-is\esm
+
+# 4) dev 启动后看预构建产物：是否存在对应文件？
+dir node_modules\.vite\deps\react-is.js
+
+# 5) dev 启动日志里是否包含该包：
+#    "dependencies optimized: xxx"（没列出 = 没被当作独立依赖预构建）
+```
+
+诊断要点：
+
+- 存在 `node_modules\.vite\deps\<pkg>.js` → 已被预构建为 ESM，没问题。
+- `require.resolve()` 抛 `MODULE_NOT_FOUND`，但包确实在用 → 典型的「传递依赖未提升」，需要修复（见 §4）。
+- 包在 `.pnpm\<pkg>@...\node_modules\<pkg>\esm` 下存在 → 有 ESM 构建，可走 §4.1 的 alias 方案。
+
+---
+
+## 3. 用 `vite build` 一次性暴露所有「具名导出丢失」
+
+dev 阶段浏览器只在加载到某个模块时才报错，一次只露一个；而 `vite build` 会走完整依赖图并链接，**所有** `is not exported` / `does not provide an export named` 会一次性列出来，适合批量排查。
+
+```bash
+npm run build-flow_dev     # 或项目对应的 build script
+```
+
+> 注意：如果 build 在早期就被 React Compiler 或 CSS hack 挡住，先按 §4.3 / §4.4 处理，否则根本走不到模块图。
+
+---
+
+## 4. 修复套路（按包的类型二选一）
+
+### 4.1 包「有 ESM 构建」→ 用 Vite alias 指向 ESM 产物
+
+适用：安装在 `.pnpm` 里的包**其中某个实例带 `esm/`**（如 `c-formily-antd@2.3.5`），但被导入的那个实例只有 CJS（如 `c-formily-antd@2.3.1`）。
+
+思路：把裸导入和 `lib/*` 子路径统一改写到一个「带 esm 的实例」上，走原生 ESM 的 `export *`，具名导出即可被正确解析。
+
+`vite.config.mts` 片段：
+
+```ts
+// 找到 .pnpm 里第一个带 esm/ 的实例
+function resolveEsmInstance(name: string, pnpmRoot: string) {
+  const entries = fs.readdirSync(pnpmRoot).filter((n) => n.startsWith(`${name}@`));
+  for (const entry of entries) {
+    const esm = path.resolve(pnpmRoot, entry, `node_modules/${name}/esm`);
+    if (fs.existsSync(esm)) return esm;
+  }
+  throw new Error(`[vite-config] no ${name} instance with an esm build found`);
+}
+
+const cFormilyAntdEsmDir = resolveEsmInstance("c-formily-antd", path.resolve(rootDir, "node_modules/.pnpm"));
+
+alias: {
+  // 注意顺序：`lib` 前缀要放在裸包名之前，才能先匹配到 `lib/*`
+  "c-formily-antd/lib": cFormilyAntdEsmDir,                       // c-formily-antd/lib/* -> esm/*
+  "c-formily-antd": path.join(cFormilyAntdEsmDir, "index.js"),    // c-formily-antd -> esm/index.js
+}
+```
+
+要点：
+
+- 顺序很重要（`find: "pkg/lib"` 要在 `find: "pkg"` 之前），否则 `pkg/lib/xxx` 会被裸包名规则吃掉。
+- alias 的 `replacement` 用绝对路径，避免二次解析到错误的实例。
+- 前提是各实例的 `@formily/*` 等内部依赖版本一致（否则会出现版本混用）。
+
+#### 4.1.1 传递依赖（未被直接导入、不在顶层 `node_modules`）→ 仍用 alias，但找「`type: module` 的实例」
+
+若包还是**另一个依赖的依赖**（如地图库 → `rbush` → `quickselect`），它既没有顶层 `node_modules/X`（所以 `optimizeDeps.include` 依然报 `Failed to resolve dependency`），也可能没有 `esm/` 目录。此时判据改为：在 `.pnpm` 里找**带 `"type": "module"`** 的实例，取其 `index.js`。
+
+> 为什么必须 `type: module`：仅带 `module`/`main` 指向 `index.js` 而缺 `type` 的实例（如 `quickselect@2.0.0`），其 `index.js` 会被 Vite 按最近 package.json 的 `type` 判为 CJS，`export default` 会被误解析。
+> 为什么 UMD 会炸：UMD 包裹器 `(function (global, factory) { ... }(this, ...))` 用顶层 `this` 当全局对象，Vite 裸供为 ESM 后顶层 `this === undefined`，抛 `Cannot set properties of undefined (setting 'quickselect')`。
+
+`vite.config.mts` 片段：
+
+```ts
+function resolveQuickselectEsm() {
+  const pnpmRoot = path.resolve(rootDir, "node_modules/.pnpm");
+  const entries = fs.readdirSync(pnpmRoot).filter((n) => n.startsWith("quickselect@"));
+  for (const entry of entries) {
+    const pkgRoot = path.resolve(pnpmRoot, entry, "node_modules/quickselect");
+    const pkgJson = path.join(pkgRoot, "package.json");
+    if (!fs.existsSync(pkgJson)) continue;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+      if (pkg.type !== "module") continue;   // 只认 type:"module" 的原生 ESM 实例
+      const entryFile = path.resolve(pkgRoot, pkg.module || pkg.main || "index.js");
+      if (fs.existsSync(entryFile)) return entryFile;
+    } catch { /* 单个实例解析失败则跳过，继续找下一个 */ }
+  }
+  throw new Error('[vite-config] no quickselect instance with "type": "module" found');
+}
+const quickselectEsm = resolveQuickselectEsm();
+
+alias: {
+  "quickselect": quickselectEsm,
+}
+```
+
+> 各版本函数签名一致（`quickselect(arr, k, left, right, compare)`），跨版本混用安全。
+
+### 4.2 包「没有 ESM 构建」（纯 CJS）→ 提升为直接依赖 + 显式 include
+
+适用：`react-is` 这类只有 `index.js`（CJS）+ `cjs/` 的共享老包。
+
+**不要用 `viteCommonjs.include`**：它只能产出 `default` 导出，而这类包多以具名导出（如 `isValidElement`）被使用，会从 `module is not defined` 变成 `does not provide an export named 'X'`。
+
+正确做法（两步）：
+
+1. 把它加进顶层依赖，让它落到顶层 `node_modules`（从而能被根解析）：
+   ```jsonc
+   // package.json  dependencies
+   "react-is": "16.13.1",
+   ```
+   ```bash
+   pnpm install
+   ```
+2. 因为现在可以从根解析，`optimizeDeps.include` 才能生效，强制预构建为 ESM：
+   ```ts
+   optimizeDeps: { include: ["react-is"] },
+   ```
+
+> 依赖预构建产物会被标记 `needsInterop: true`，Vite 会用 CJS interop 正确改写具名导入。
+
+> **多条 `require is not defined` / es-shims 家族闭包**：当报错包的**父包**是「被 `viteCommonjs.include` 转换」的 CJS 入口包时（如 `deep-equal`、`geojson-equality`），其纯 CJS 依赖（`object-keys`、`regexp.prototype.flags`、`define-properties`、`object-is`、`is-arguments`、`is-regex` …）会逐一被独立裸供。此时**不要**把这些叶子包逐个加入 `viteCommonjs.include`，而是**把入口包提升为直接依赖 + `optimizeDeps.include`**——预构建会把入口包的**整个 es-shims CJS 闭包**内联成一个 ESM 文件（`node_modules/.vite/deps/<entry>.js`），同时解决该链路上的全部裸供问题。记得把入口包从 `viteCommonjs.include` 里删掉，避免被二次转换。
+
+### 4.3 构建期 CSS 老 IE hack → `errorRecovery`
+
+```ts
+vite: {
+  css: {
+    lightningcss: { errorRecovery: true },
+  },
+},
+```
+
+把 `*zoom`/`*display`/`*width` 等早已失效的 IE hack 剥离，降级为 warning 而非中断构建。
+
+### 4.4 React Compiler 缺包 → 关闭或补装
+
+`@hzab/vite-config` 默认 `reactCompiler: "build-only"`，build 时若没有 `babel-plugin-react-compiler` 会直接失败。二选一：
+
+```ts
+// 方案 A：不打算启用 React Compiler
+reactCompiler: false,
+
+// 方案 B：真正启用（先装依赖）
+// pnpm add -D babel-plugin-react-compiler
+// reactCompiler: "build-only",
+```
+
+### 4.5 浏览器端 `process` 未定义 → `define + process polyfill`
+
+适用：webpack 迁移到 Vite，源码或依赖里出现 `ReferenceError: process is not defined` 的包/代码。
+
+**为何会炸**：webpack 会 polyfill 全局 `process` 并经 DefinePlugin 注入 `process.env.*`；Vite 默认**只**替换 `process.env.NODE_ENV`，既不提供 `process` 全局，也不替换其余 `process.env.*`。于是源码/依赖里的 `process.env.BUSINESS_PLATFORM` 这类表达式在浏览器端原样保留，一遇到 `process` 即抛错。
+
+**修复（两步，缺一不可）**：
+
+1. **`vite.define` 注入**（对齐 webpack `processEnv`）：把 webpack 侧注入的键（`WEBPACK_ENV` / `WEBPACK_PUBLIC_PATH` / `PACKAGE_VERSION`）与用户自定义键（`BUSINESS_PLATFORM`）以及源码直接引用的 `process.env.*`（如 `APP_VERSION`）全部定义。键必须带引号，值经 `JSON.stringify`：
+
+   ```ts
+   vite: {
+     define: {
+       "process.env.BUSINESS_PLATFORM": JSON.stringify(process.env.BUSINESS_PLATFORM || "unknown"),
+       "process.env.WEBPACK_ENV": JSON.stringify(mode),
+       "process.env.WEBPACK_PUBLIC_PATH": JSON.stringify(""),
+       "process.env.PACKAGE_VERSION": JSON.stringify(PACKAGE_VERSION),
+       "process.env.APP_VERSION": JSON.stringify(PACKAGE_VERSION),
+     },
+   }
+   ```
+
+   覆盖**应用源码**与 **build**：`vite build` 产物中不应再有裸 `process.env.*`。
+
+2. **`index.html` 全局 `process` polyfill**：`vite.define` **不作用于 `optimizeDeps` 预构建产物**。被预构建的依赖（尤其 `main` 指向 `src` 的源码包，如 `@hzab/data-model`）内部的 `process.env.*` 在 dev 仍会裸供。在 `index.html` 顶部注入：
+   ```html
+   <script>
+     window.process = window.process || { env: {} };
+   </script>
+   ```
+   兜底所有预构建 / 第三方裸 `process` 引用。
+
+> 验证：`vite build` 后 `grep process.env dist` 为空 = define 覆盖了应用层；但 `.vite/deps/*.js`（预构建产物）里仍有 `process.env.*` = 依赖层未被 define 覆盖，需 polyfill。二者都要做，才能同时保住 dev 与 build。
+
+### 4.6 `.js` 里写 JSX / 默认导出缺失 / pnpm 未提升依赖
+
+**`.js` 里的 JSX（`Unexpected JSX expression`）**：webpack 靠 babel-loader 转 `.js` 的 JSX；Vite 8 的 transform 由 **oxc** 接管——`OxcOptions` 已 `Omit lang`（按扩展名推断），`esbuild` 配置被忽略（提示 `esbuild options will be ignored`）。解法：
+
+1. `src/` 下含 JSX 的 `.js` 改名 `.jsx`；
+2. `node_modules` 里不可改的来源包（如 `@hzab/*` 的 `*.js`）用自定义 pre-transform 插件：`enforce:"pre"` + `transformWithOxc(code, id, { lang:"jsx", jsxRuntime:"automatic" })`，一段同时覆盖 src 与 node_modules。
+
+**`MISSING_EXPORT "default"`**：`import style from "./x.less"`（Vite 的 `.less` 无 default export）→ 改副作用 `import "./x.less"`；`import worker from "pkg/...worker.entry"`（webpack 打包 worker）→ Vite 用 `?url` 取地址。
+
+**`Failed to resolve import "pkg/..."`（pnpm 隔离）**：业务源码直接 import 了只作为传递依赖存在的包，未被提升到顶层。逐一提升为直接依赖 + `pnpm install`（可用脚本扫描 `src` 裸包导入、`require.resolve` 检测未提升项批量定位）。
+
+---
+
+## 5. 复用自查清单（新项目接入时逐条核对）
+
+1. `pnpm install` 后，app 依赖的**共享 CJS 老包**（`react-is`、`object-assign`、`classnames`、`prop-types`、`dayjs` …）是否在顶层 `node_modules`？不在 → 走 §4.2。
+   1.1 报 `require is not defined`（而非 `module is not defined`）→ 先定位**父入口包**（被 `viteCommonjs.include` 转换的那个 CJS 包，如 `deep-equal`、`geojson-equality`），**把入口包**提升 + `optimizeDeps.include`（其 es-shims 闭包会整体内联），别逐个加叶子包。入口包同时从 `viteCommonjs.include` 移除。
+2. 报 `does not provide an export named 'X'` → 查该包在 `.pnpm` 里是否有带 `esm/` 的实例；有 → §4.1；没有但含 `src/` 原生 TS/JS ESM（如 `@hzab/classnames-utils`）→ §4.1 alias 到 `src`；都没有 → §4.2。
+3. 报 `Cannot set properties of undefined (setting 'X')` → UMD 顶层 `this` 裸供；查该包在 `.pnpm` 里是否有 `"type": "module"` 的实例；有 → §4.1.1。
+4. 报 `module is not defined` → 一定是「未预构建的 CJS 被裸供」，先确认包在顶层，再 `optimizeDeps.include`。
+5. `optimizeDeps.include` 报 `Failed to resolve dependency` → 说明还没到顶层，先加依赖 + `pnpm install`，再 include。
+6. 别用 `viteCommonjs` 去救「具名导出」：它只产 `default` 导出。
+7. 构建报 LightningCSS `star property hack` → §4.3。
+8. 构建报 `babel-plugin-react-compiler` 缺失 → §4.4。
+9. 用 `vite build` 做全量「导出缺失」巡检，能一次暴露所有同款问题。
+10. 工具命令被钩子/脚本引用（如 `.husky/pre-commit` 里的 `npx lint-staged`）→ 该工具（`lint-staged` / `prettier`）**必须**在 `devDependencies`。pnpm 不会把传递依赖的 bin 链接到顶层 `node_modules/.bin`，只当它是直接依赖时才会（§6 末行）。
+
+---
+
+## 6. 本项目已落地实例
+
+| 包                                                                | 问题                                                                      | 采用的修复                                                               |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `c-formily-antd@2.3.1`（仅 CJS 实例）                             | `useFormLayout` 具名导出丢失                                              | §4.1 alias 到带 esm 的 2.3.5 实例                                        |
+| `turf-jsts`（传递依赖）                                           | `BufferOp` 具名导出丢失                                                   | §4.1 alias 到原生 ESM `jsts.mjs`                                         |
+| `@hzab/classnames-utils@0.0.2`（webpack 打的 UMD CJS，无 `esm/`） | `NO_PREFIX_TYPE` 等具名导出丢失                                           | §4.1 alias 到原生 TS ESM 源 `src/index.ts`                               |
+| `quickselect`（`rbush` 的传递依赖）                               | `Cannot set properties of undefined (setting 'quickselect')`              | §4.1.1 alias 到 `type: module` 的原生 ESM `index.js`                     |
+| `react-is@16.13.1`（纯 CJS、未提升）                              | `module is not defined`                                                   | §4.2 加直接依赖 + `optimizeDeps.include`                                 |
+| `deep-equal@1.1.2`（CJS 入口包）                                  | `require is not defined`（其依赖 `object-keys` 被裸供）                   | §4.2 加直接依赖 + `optimizeDeps.include`；从 `viteCommonjs.include` 移除 |
+| `geojson-equality@0.1.6`（CJS 入口包）                            | `require is not defined`（同经 `deep-equal`）                             | §4.2 加直接依赖 + `optimizeDeps.include`；从 `viteCommonjs.include` 移除 |
+| 老 CSS 星号 hack                                                  | `lightningcss ... Semicolon`                                              | §4.3 `errorRecovery`                                                     |
+| React Compiler                                                    | `Cannot find package 'babel-plugin-react-compiler'`                       | §4.4 `reactCompiler: false`                                              |
+| `lint-staged`（`.husky/pre-commit` 引用）                         | `git commit` 报 `'lint-staged' 不是内部或外部命令`（pre-commit 退出码 1） | 加为直接依赖 `13.2.3` + `pnpm install`                                   |
+
+> 对应改动均在 `vite.config.mts` 与 `package.json`（react-is / deep-equal / geojson-equality 直接依赖 + `pnpm-lock.yaml`）。`lint-staged` 一行属「直接依赖缺失」的典型 pnpm 隔离问题：钩子引用的命令若未声明为直接依赖，pnpm 不会把它的 bin 链接到顶层。

package/docs/vs-ccc-vite-config.md

@@ -0,0 +1,26 @@
+# 相对 Vite 仓 `@ccc/vite-config` 的差异
+
+> 更新日期：2026-08-28
+> 当前仓：`tooling/vite-config`（`@hzab/vite-config` **0.0.2-alpha.0**）
+> 对照仓：`~/Workbench/Vite/monorepo-packages/tooling/vite-config`（`@ccc/vite-config` **0.0.1**）
+
+JS `import.meta.env.PUBLIC_PATH` 与 `exports["./client"]` 已于 2026-08-28 从 Vite 仓回灌，
+实施记录见 [sync-public-path.md](./sync-public-path.md)。两边工厂能力已对齐。
+
+2026-08-27 分叉快照作废：不要按旧表「对照仓缺 `resolveTilde` / 本包缺 `PUBLIC_PATH`」去改。
+
+## 当前仍有的差异（刻意保留）
+
+| 项           | 当前仓 `@hzab`                         | 对照仓 `@ccc`              | 原因                         |
+| ------------ | -------------------------------------- | -------------------------- | ---------------------------- |
+| 包名 / 版本  | `@hzab/vite-config` `0.0.2-alpha.0`    | `@ccc/vite-config` `0.0.1` | scope 即仓身份               |
+| 依赖版本     | 钉死（`less` `4.1.3` 等）              | `catalog:`                 | 本仓可独立发版               |
+| 覆盖率门槛   | statements / lines / functions 70；无 branches | 另加 `branches: 60` | 本仓 V8 branch 计数不稳定（见 [REVIEW.md](../REVIEW.md) §6） |
+| 发布配置     | `publish-target.json`（aliyun-ld / aliyun-old） | 无 / 不同           | 本仓双私有源                 |
+
+模板 `vite-env.d.ts` 两边都引用各自 scope 的 `./client`。`svg-react` 插件名两边都还是 `ccc:svg-react`。
+
+## 相关文档
+
+- 迁入本仓时的问题存档：[docs/vite-config-migration-issues.md](../../../docs/vite-config-migration-issues.md)
+- 公开 API：[api.md](./api.md)

package/docs/webpack-gap.md

@@ -0,0 +1,107 @@
+# 相对 `@hzab/webpack-config` 的能力差距
+
+对照范围：webpack 侧 `mergeConfig` 选项与 base / local / prod / page / components 静态层；
+Vite 侧以 `createAppViteConfig` / `createLibraryViteConfig` 与 [API](./api.md) 为准。
+
+两边定位不同：`webpack-config` 仍是绑定本仓约定的模板；`vite-config` 是解耦工厂
+（alias / 代理 / 部署由消费方传入）。因此「少了」分三类：**真实缺口**、**Vite 原生已覆盖**、
+**刻意不搬的仓库耦合**。
+
+```mermaid
+flowchart LR
+  subgraph webpack [webpack-config]
+    page[page app]
+    lib[componentsMode UMD]
+    mock[dev mock]
+    define[DefinePlugin env]
+  end
+  subgraph vite [vite-config]
+    app[createAppViteConfig]
+    libFactory[createLibraryViteConfig]
+    vitest[createPackageVitestConfig]
+    hash[hashDeployPlugin]
+    svgr[svgReactPlugin]
+  end
+  page --> app
+  page --> hash
+  svgr --> app
+  lib --> libFactory
+  define --> nativeEnv[MODE BASE_URL vite.define]
+  mock --> skipMock[devProxy or consumer plugins]
+```
+
+## 已对齐（不必当缺口）
+
+| webpack                                                   | vite-config                                                                                                                                                   |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootDir` / `repositoryRoot`                              | 同名；commit 默认从 `rootDir` 读                                                                                                                              |
+| `isHash` + `hashPublicPath` + `writeHash` + `hashCleanup` | `hashDeploy` + `base` + `deployRoot` + `hashCleanup`；Vite 侧契约校验更严                                                                                     |
+| `copyPublicConfig` / `handlePreConfig`                    | `publicConfig` 插件复制（默认产物 `config/`，可 `dest: "public/config"`）                                                                                     |
+| CopyPlugin `public → public/`                             | `publicAssets`                                                                                                                                                |
+| 额外 CopyPlugin patterns                                  | `copy` / `copyPlugin`（封装 peer `vite-plugin-static-copy`）                                                                                                  |
+| `lessLoaderOptions`                                       | `less.additionalData` / `modifyVars` / `javascriptEnabled`                                                                                                    |
+| `userConf` / `beforeBuild`                                | `vite`（`mergeConfig`）→ `configure`                                                                                                                          |
+| HTTPS / `open`                                            | `useHttps` / `openBrowser`                                                                                                                                    |
+| 构建清空产物                                              | `build.emptyOutDir: true`                                                                                                                                     |
+| HTML `PUBLIC_PATH`                                        | `vite-plugin-html` 注入 `PUBLIC_PATH`；额外键走 `htmlData`                                                                                                    |
+| SVG 资源 URL                                              | Vite 默认 `import url from "./x.svg"`                                                                                                                         |
+| SVG → React 组件                                          | `svgr` / `svgReactPlugin`：`import Icon from "./x.svg?react"`（默认关）                                                                                       |
+| `onRun` / `onDone`                                        | 同名；Vite 侧 `onDone` 在 Hash `writeBundle` 之后，写入失败不调用                                                                                             |
+| `componentsMode` UMD `lib/` + externals；local 预览       | `createLibraryViteConfig`：默认 UMD → `lib/index.js`；默认 externals 仅 `react` / `react-dom`；serve 预览不外置、无 Hash。不默认 `example/` 与 antd / Formily |
+
+vite-config **多出来**、webpack 没有：Vitest 工厂、React Compiler、独立发布、Hash 契约校验。
+
+## 真实缺口（工厂层没有对等能力）
+
+### 1. Hash 目录不要时间戳：`timeHash: false`
+
+webpack：`{commit}`；默认 `{commit}-{timestamp}`。
+
+vite：`createHashBuildDirName` **总是** `{commit}-{timestamp}`（失败回退 `local-<timestamp>`），工厂没有关闭时间戳的开关。`hashCleanup` 还依赖目录名里的时间戳。
+
+### 2. Less `javascriptEnabled` 默认值
+
+webpack 样式规则**强制** `javascriptEnabled: true`（注释写 formily 需要）。
+
+vite-config 仅在传入 `less.javascriptEnabled` 时才设置；不传则跟 Vite/Less 默认走。用 formily 内联 JS Less 的消费方必须自己打开。
+
+## Vite 原生已覆盖（不必做成工厂选项）
+
+这些在 webpack 里是显式 loader/plugin，Vite 默认就有，不算 vite-config「少功能」：
+
+- TS/JSX 编译（对应 babel-loader + `@hzab/*/src` include）
+- 图片 / 字体 / 文本资源 filename 规则
+- CSS / CSS Modules / 构建抽 CSS（`splitCssFile` / MiniCssExtract）
+- SPA `historyApiFallback`、HMR、端口占用自增
+- 开发 sourcemap；生产 minify
+- 文件系统缓存（`node_modules/.vite`；`noCachePackages` 无直接对等，调试 workspace 包用 alias / `optimizeDeps.exclude`）
+- `devServer.port: 3000`（Vite 默认 5173，可用 `vite.server.port` 覆盖）
+- webpack `DefinePlugin` / `processEnv`：不必做成工厂选项，也不搬 `WEBPACK_*` 命名
+  - `WEBPACK_ENV` → 应用 JS 读 `import.meta.env.MODE`（本仓测试包是 `test`，不是 webpack 的 `development`；本地 serve 是 `development`，不是 `local`）。不要用 `import.meta.env.PROD` 区分测试包与生产包——Vite 里所有 `build` 都是 `PROD === true`
+  - `WEBPACK_PUBLIC_PATH`：打包资源仍读 `import.meta.env.BASE_URL`（相对 hash 必须是 `./`）。根入口 `fetch` / 动态 URL 用工厂注入的 `import.meta.env.PUBLIC_PATH`（相对 hash 为 `./{hash}/`）。Webpack `getPublicUrl` 只服务 Webpack 项目
+  - `WEBPACK_HASH` → 已包含在 `import.meta.env.PUBLIC_PATH` 里；构建 / 部署侧仍有返回值 `buildDirHash` 与产物 `hash.txt`。不必再单独注入构建号；要展示则消费方自己 `vite.define`
+  - `PACKAGE_VERSION` / 额外键 → 消费方 `vite.define`（应从**应用** `package.json` 读，不要学 webpack 注入工厂包版本）
+  - 真正的运行时业务配置继续走 `publicConfig` → `window.globalConfig`
+
+`ProvidePlugin({ React: "react" })` 也不建议搬：`@vitejs/plugin-react` 默认 automatic JSX runtime，一般不必全局注入 `React`。
+
+## 刻意不搬（webpack 的仓库耦合）
+
+审查已明确禁止硬编码本仓约定。下列是 webpack 有、vite **不应**默认复制的：
+
+- 固定 alias `@` / `@assets` / `@service`
+- Babel 只转 `@hzab/*/src`
+- 组件 externals 写死 antd / Formily / `@hzab/form-render`
+- 组件预览目录写死 `./example`
+- 配置生成时默认清空并复制 `public/config`（vite 需显式 `publicConfig`）
+- webpack 默认常开的 `?svgEle` SVGR 契约（vite 用社区 `?react`，且默认关闭）
+- 开发态类型检查：webpack local 挂 `ForkTsCheckerWebpackPlugin({ async: true })`。Vite 官方只转译、不查类型；vite-config 不内置 `tsc` / `vue-tsc` / `vite-plugin-checker`。消费方用 IDE 与构建脚本 `tsc -b`，或自行 `plugins: [checker({ typescript: true })]`
+- 开发 Mock：webpack local 且 `closeMock === false` 时挂 `webpack-plugin-mock`（独立端口，默认 3100）。vite-config 不内置 mock 插件或独立 mock 端口；连真实后端用 `devProxy`；要本地桩则消费方 `plugins` 自挂 `vite-plugin-mock` / MSW / `configureServer`
+
+## 若以后要补：建议优先级
+
+有明确迁移或复用场景再做，不默认跟 webpack 对齐。
+
+1. **中**：`timeHash`、Less 默认 `javascriptEnabled` 的文档或选项默认值
+
+返回 [文档目录](./README.md)。

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@hzab/vite-config",
+  "version": "0.0.2-alpha.0",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Vite / Vitest configuration factories for consumer apps and packages",
+  "author": "CaiYansong",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "import": "./dist/vitest.js",
+      "require": "./dist/vitest.cjs"
+    },
+    "./src/*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    },
+    "./client": {
+      "types": "./src/client.d.ts"
+    },
+    "./svg-react": {
+      "types": "./src/svg-react.d.ts",
+      "import": "./dist/svg-react-runtime.js",
+      "require": "./dist/svg-react-runtime.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@rolldown/plugin-babel": "^0.2.0",
+    "@svgr/core": "^8.1.0",
+    "@svgr/plugin-jsx": "^8.1.0",
+    "@svgr/plugin-svgo": "^8.1.0",
+    "@vitejs/plugin-basic-ssl": "^2.0.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "happy-dom": "^20.0.0",
+    "vite": "^8.0.0",
+    "vite-plugin-html": "^3.2.0",
+    "vite-plugin-static-copy": "^4.0.0",
+    "vitest": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@svgr/core": {
+      "optional": true
+    },
+    "@svgr/plugin-jsx": {
+      "optional": true
+    },
+    "@svgr/plugin-svgo": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.58.13",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@svgr/core": "^8.1.0",
+    "@svgr/plugin-jsx": "^8.1.0",
+    "@svgr/plugin-svgo": "^8.1.0",
+    "@types/node": "^24.0.0",
+    "@vitejs/plugin-basic-ssl": "^2.3.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "happy-dom": "^20.0.0",
+    "less": "4.1.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.2.1",
+    "vite-plugin-html": "^3.2.2",
+    "vite-plugin-static-copy": "^4.1.1",
+    "vitest": "^4.1.10",
+    "@hzab/typescript-config": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --coverage",
+    "api-report": "api-extractor run --local --verbose"
+  }
+}

package/src/client.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /**
+   * 根入口静态资源前缀（含相对 Hash 的 `./{hash}/`）。
+   * 用于 JS `fetch` / 动态 URL，与 HTML 子目录模板里的 `PUBLIC_PATH`（`./`）不是同一个值。
+   */
+  readonly PUBLIC_PATH: string;
+}