@hzab/vite-config 0.0.2-alpha.0 → 0.0.3-alpha.1

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

@@ -1,26 +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)
+# 相对 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/archive/vite-config-migration-issues.md](../../../docs/archive/vite-config-migration-issues.md)
+- 公开 API：[api.md](./api.md)

package/docs/webpack-gap.md

@@ -1,107 +1,108 @@
-# 相对 `@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)。
+# 相对 `@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`；清理语义两侧一致（同一模式串 + 5 分钟近期保护），Vite 侧契约校验更严                                    |
+| `hashDirName` 模式串（token：`hash` / `timestamp` / 日期 token） | 同名 `hashDirName`，token 语义相同（两侧各自实现，不互相依赖）                                                                                                |
+| `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`、`hashDirName`~~（已对齐）
+
+webpack：`timeHash: false` → `{commit}` 已移除（同 commit 的多次构建会互相覆盖）；默认 `{commit}-{timestamp}`，`hashDirName` 模式串可任意组合 token（`hash` / `timestamp` / `YYYYMMDDHHmmssSSS` 等日期 token），例如 `hash-timestamp-YYYYMMDDHHmmssSSS` → `{commit}-{timestamp}-{YYYYMMDDHHmmssSSS}`、`hash-YYYYMMDDHHmmssSSS` → `{commit}-{YYYYMMDDHHmmssSSS}`。
+
+vite：`createAppViteConfig` 同样提供 `hashDirName` 模式串，token 与 webpack 完全同语义（默认 `hash-timestamp` → `{commit}-{Date.now()}`，非 Git 仓库回退 `local-<timestamp>`）；`hashCleanup` 按同一模式串识别历史目录，并对目录名时间戳距今不足 5 分钟的目录做并发保护。旧的 `hashTimestamp: "epoch" | "datetime"` 已移除，迁移写法见 [Hash 目录名模式串](./api.md#hash-目录名模式串hashdirname)。
+
+### 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

@@ -1,6 +1,6 @@
 {
   "name": "@hzab/vite-config",
-  "version": "0.0.2-alpha.0",
+  "version": "0.0.3-alpha.1",
   "private": false,
   "type": "module",
   "publishConfig": {

package/src/client.d.ts

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