@oj-module/cli 0.2.64 → 0.2.66

package/src/esm-exports.ts

@@ -14,14 +14,19 @@
  * 本模块只做「扫描产物文本、回答谁导出/导入了什么」，不含修复逻辑，
  * 供 shell 构建（门禁，失败即中断）与 tests/ 共用，避免两套正则漂移。
  *
- * 解析口径：只认**行首**的 `import` / `export`。esbuild 与 vite 在
- * `minify: false` 下顶层语句一律顶格输出，依赖内部的代码有缩进，
- * 借此把「字符串字面量里恰好写了 import」这类误报压到最低。
+ * 解析口径：`es-module-lexer` 真词法扫描，而非行首正则。
+ * 早先的实现假设「esbuild/vite 在 `minify: false` 下顶层语句一律顶格」，一旦
+ * 共享资产开启压缩（`minifyWhitespace` 会把 `export{a as b}` / `}from"react"`
+ * 挤成一行且行内任意位置），行首锚定的正则全部失配 → 门禁集体误报「零具名导出」
+ * 和「裸说明符未登记」。词法扫描只依赖语法、与压缩/换行无关，故换掉。
+ * 顺带消灭了「字符串字面量里恰好写了 import/from」的误报（原先靠行首锚定压制）。
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { ImportType, initSync, parse as lexModule } from "es-module-lexer";
+
 /** 一个 ESM 文件的导出面 */
 export interface EsmExports {
 	/** 静态具名导出（不含 `default`、不含 `export *` 透传的部分） */
@@ -56,22 +61,6 @@ export interface EsmImport {
 	needsDefault: boolean
 }
 
-/**
- * `export { a, b as c }`（本地导出块）与 `export { a, b as c } from "x"`（再导出）
- * 的公共部分：取出**对外暴露**的名字（`b as c` 取 `c`）。
- */
-function exportedNamesFromClause(clause: string): string[] {
-	return clause
-		.split(",")
-		.map(part => part.trim())
-		.filter(Boolean)
-		.map((part) => {
-			const as = part.split(/\s+as\s+/);
-			return (as[as.length - 1] ?? part).trim();
-		})
-		.filter(name => name !== "default");
-}
-
 /**
  * `import { a, b as c }` 中被**请求**的名字。
  *
@@ -88,51 +77,75 @@ function importedNamesFromClause(clause: string): string[] {
 		.filter(name => name !== "default");
 }
 
+/** wasm 实例化只需一次；按需初始化，避免「只是 import 一下」的消费方付启动开销 */
+let lexReady = false;
+function lex(source: string): ReturnType<typeof lexModule> {
+	if (!lexReady) {
+		initSync();
+		lexReady = true;
+	}
+	return lexModule(source);
+}
+
+/** 语句文本；`ss`/`se` 是 lexer 给出的整条语句区间（含分号） */
+function statementAt(source: string, ss: number, se: number): string {
+	return source.slice(ss, se);
+}
+
+/**
+ * 从一条 `import … from "x"` / `export … from "x"` 语句里分出关键字与子句。
+ *
+ * 语句边界已由 lexer 确定，这里只处理语句内部的切片，因此不再需要行首锚定，
+ * 压缩后（`import{a as b}from"react"`）同样成立。
+ */
+function clauseOf(statement: string): { keyword: "import" | "export", clause: string } | undefined {
+	const head = /^\s*(import|export)\b/.exec(statement);
+	if (!head)
+		return undefined;
+	const rest = statement.slice(head[0].length);
+	// `from` 后必须紧跟说明符字符串，才不会误取子句里的同名标识符
+	const fromIdx = rest.search(/\bfrom\s*["']/);
+	if (fromIdx < 0)
+		return undefined;
+	return { keyword: head[1] as "import" | "export", clause: rest.slice(0, fromIdx) };
+}
+
 /** 解析产物的静态导出面 */
 export function parseEsmExports(source: string): EsmExports {
+	const [imports, exports] = lex(source);
 	const names = new Set<string>();
+	let hasDefault = false;
 
-	// 收集全部 export 子句（本地导出块 + 再导出），具名与 default 两种判定共用
-	const clauses: string[] = [];
-	for (const m of source.matchAll(/^export\s*\{([^}]*)\}(?:\s*from\s*["'][^"']+["'])?\s*(?:;\s*)?$/gm)) {
-		clauses.push(m[1] ?? "");
-	}
-
-	for (const clause of clauses) {
-		for (const name of exportedNamesFromClause(clause))
-			names.add(name);
+	for (const exp of exports) {
+		if (exp.n === "default")
+			hasDefault = true;
+		else
+			names.add(exp.n);
 	}
 
-	// 声明式导出：export const/let/var/function/class/async function
-	for (const m of source.matchAll(/^export\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function\*?|class)\s+([A-Za-z_$][\w$]*)/gm)) {
-		names.add(m[1]!);
-	}
+	// `export * from "x"` 不产生具名导出（静态不可展开），lexer 也不把它列进 exports，
+	// 只能从「语句以 export 开头、星号之后不带 as」反推。
+	// `export * as ns from "x"` 是有名字的导出（ns），导出面仍可静态确定，不算在内。
+	const hasStarReexport = imports.some((imp) => {
+		if (imp.t !== ImportType.Static || imp.ss < 0)
+			return false;
+		return /^export\s*\*(?!\s*as\b)/.test(statementAt(source, imp.ss, imp.se));
+	});
 
-	// default 有两副面孔：声明式 `export default …`，或子句里的 `x as default`
-	// （esbuild 产出的正是后者，形如 `rad_shim_xxx_default as default`）
-	const hasDefaultClause = clauses.some(clause => clause
-		.split(",")
-		.map(part => part.trim())
-		.some(part => /\bas\s+default$/.test(part)));
-
-	return {
-		names,
-		hasDefault: /^export\s+default\b/m.test(source) || hasDefaultClause,
-		hasStarReexport: /^export\s*\*/m.test(source),
-	};
+	return { names, hasDefault, hasStarReexport };
 }
 
 /**
  * 解析产物消费了哪些说明符的哪些具名导出。
  *
- * 覆盖三种形态（均为 esbuild / vite 非压缩产物的常见写法）：
- *   `import { a, b as c } from "x"`、`import { a } from "x"`（多行）、
- *   `export { a } from "x"`（再导出同样是消费）。
+ * 覆盖：`import { a, b as c } from "x"`、`import X, { a } from "x"`、
+ * `export { a } from "x"`（再导出同样是消费）。
  *
  * 不覆盖：`import * as ns from "x"`、动态 `import("x")` 后取属性——
  * 这些都拿不到具名绑定，无从校验。
  */
 export function parseEsmImports(source: string): EsmImport[] {
+	const [imports] = lex(source);
 	const found = new Map<string, { names: Set<string>, needsDefault: boolean }>();
 
 	const slot = (specifier: string) => {
@@ -144,25 +157,30 @@ export function parseEsmImports(source: string): EsmImport[] {
 		return entry;
 	};
 
-	// 具名导入（允许跨行）；用 [^;]*? 兜住语句边界，避免跨越到下一条语句
-	for (const m of source.matchAll(/^import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/gm)) {
-		const entry = slot(m[2]!);
-		for (const name of importedNamesFromClause(m[1] ?? ""))
-			entry.names.add(name);
-	}
+	for (const imp of imports) {
+		// 动态 import / import.meta 不带静态具名绑定
+		if (imp.t !== ImportType.Static || imp.ss < 0 || !imp.n)
+			continue;
+		const parsed = clauseOf(statementAt(source, imp.ss, imp.se));
+		if (!parsed)
+			continue;
 
-	// 具名再导出
-	for (const m of source.matchAll(/^export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/gm)) {
-		const entry = slot(m[2]!);
-		for (const name of importedNamesFromClause(m[1] ?? ""))
-			entry.names.add(name);
-	}
+		const entry = slot(imp.n);
+		const brace = /\{([^}]*)\}/.exec(parsed.clause);
+		if (brace) {
+			for (const name of importedNamesFromClause(brace[1] ?? ""))
+				entry.names.add(name);
+		}
 
-	// default 导入：`import X from "x"`（X 非 { 、非 *）
-	// 不能假定它一定可用——只有 default 的包若 shim 没兜住，浏览器同样是
-	// "does not provide an export named 'default'"
-	for (const m of source.matchAll(/^import\s+([A-Za-z_$][\w$]*)\s+from\s*["']([^"']+)["']/gm)) {
-		slot(m[2]!).needsDefault = true;
+		// default 导入：子句去掉 `{…}` 后仍剩标识符（`X` / `X,`）。
+		// `* as ns` 是命名空间导入，不消费 default。
+		// 不能假定它一定可用——只有 default 的包若 shim 没兜住，浏览器同样是
+		// "does not provide an export named 'default'"。
+		if (parsed.keyword === "import") {
+			const head = parsed.clause.replace(/\{[^}]*\}/g, "").trim();
+			if (head && !head.startsWith("*"))
+				entry.needsDefault = true;
+		}
 	}
 
 	return [...found].map(([specifier, entry]) => ({
@@ -233,24 +251,88 @@ export function collectDynamicRequires(distDir: string): DynamicRequireHit[] {
 }
 
 /**
- * 产物引用的全部裸说明符（三种形态：具名/副作用 import、`import("x")`、再导出）。
+ * 产物引用的全部裸说明符（静态/副作用 import、`import("x")`、再导出）。
  *
  * 浏览器只能解析 importmap 里登记过的裸说明符，漏一个就是
  * `Failed to resolve module specifier` 白屏。
  */
 export function parseBareSpecifiers(source: string): string[] {
+	const [imports] = lex(source);
 	const found = new Set<string>();
-	// 行首锚定，规避字符串字面量里的假阳性（P3.5 教训）
-	const pattern = /^import\s*\(\s*["']([^"']+)["']\s*\)|^(?:import|export)\s[^;]*?from\s*["']([^"']+)["']|^import\s+["']([^"']+)["']/gm;
-	for (const m of source.matchAll(pattern)) {
-		const spec = m[1] ?? m[2] ?? m[3];
-		if (!spec || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("data:") || spec.startsWith("http"))
+	// lexer 已给出每条语句的说明符原文；非字符串字面量（`import(x)`）为 undefined，跳过
+	for (const imp of imports) {
+		const spec = imp.n;
+		if (!spec)
+			continue;
+		if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("data:") || spec.startsWith("http"))
 			continue;
 		found.add(spec);
 	}
 	return [...found];
 }
 
+/**
+ * 产物的**静态**依赖说明符：`import … from "x"`、副作用 `import "x"`、再导出。
+ *
+ * 与 {@link parseBareSpecifiers} 的差别有两点，都是为了算「首屏静态闭包」：
+ *   - **排除动态 `import("x")`**：那是懒加载，不在首屏关键路径上，预取它会白拉；
+ *   - **保留相对/绝对路径**：闭包要顺着 `/assets/x.hash.js` 继续走，不能只看裸名。
+ *
+ * 静态图的切分口径与浏览器一致（缓存模块记录前先取完整静态图），所以这里能算出
+ * 「浏览器一定会请求的最小集合」。
+ */
+export function parseStaticSpecifiers(source: string): string[] {
+	const [imports] = lex(source);
+	const found = new Set<string>();
+	for (const imp of imports) {
+		// d === -1 才是静态导入；`import("x")` 的 d 是 `(` 的偏移
+		if (imp.d !== -1 || !imp.n)
+			continue;
+		found.add(imp.n);
+	}
+	return [...found];
+}
+
+/**
+ * 首屏静态依赖闭包：从入口出发，顺着**静态** import 一直走到没得走。
+ *
+ * 这就是浏览器一定会请求的集合（ESM 语义：先取完整静态图再执行），所以可以放心
+ * 全量预取；动态 `import()` 不在其中。裸说明符经 importmap 解析，相对路径按当前
+ * 文件所在目录拼。
+ *
+ * `readAsset` 返回 undefined 表示读不到（跨源 CDN 资产、或缺失文件）：该 URL 仍算
+ * 闭包成员（预取它对浏览器有效），但不再往下展开。
+ *
+ * 与构建脚本共用同一份实现，是为了让测试能重算一遍对撞产物——两套实现必然漂移。
+ */
+export function collectStaticClosure(
+	entryUrl: string,
+	importmap: Record<string, string>,
+	readAsset: (url: string) => string | undefined,
+): string[] {
+	const seen = new Set<string>();
+	const queue = [entryUrl];
+	while (queue.length) {
+		const url = queue.shift()!;
+		if (seen.has(url))
+			continue;
+		seen.add(url);
+		const source = readAsset(url);
+		if (source === undefined)
+			continue;
+		for (const spec of parseStaticSpecifiers(source)) {
+			const target = spec.startsWith("/")
+				? spec
+				: spec.startsWith(".")
+					? resolve("/", url.slice(0, url.lastIndexOf("/") + 1), spec)
+					: importmap[spec];
+			if (target)
+				queue.push(target);
+		}
+	}
+	return [...seen];
+}
+
 /** 一处「资产引用了 importmap 未登记的裸说明符」 */
 export interface UnresolvedSpecifier {
 	file: string

package/src/shared-deps.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 /**
  * 共享依赖表 —— 单一常量源（设计文档 §4.3，解决 B11 / B12）。
  *
@@ -21,15 +23,18 @@ export interface SharedDepEntry {
 	/** 硬共享：模块不得自带 */
 	hard: boolean
 	/**
-	 * 软共享但「不进宿主首屏」：宿主 shell 不预构建该资产、importmap 不列该键，
-	 * 模块若 import 它则自行打包进模块产物（设计文档 §4.3 的「软共享缺席→模块自带
-	 * 副本兜底」语义）。用于**仅模块使用、宿主与共享 chunk 永不 import**的重型依赖
-	 * （编辑器 / 图表 / Markdown / 拖拽 …），避免把它们 5~6MB 的体量无谓铺进
-	 * shell-dist 并要求公开链路多传一堆文件。宿主侧有真实 import 的共享依赖
-	 * （antd / pro-components / icons 内部依赖的 motion / react-jss / dayjs /
-	 * zustand 等）绝不能标 bundle —— 否则会被 antd 等共享 chunk 经 importmap 解析
-	 * 不到而 404。判定依据：宿主 host.tsx + runtime.js 的传递 import 图，以及
-	 * antd/pro-components/icons 的传递依赖图，都不含这些说明符。
+	 * 模块自打包：宿主 shell 不预构建该资产、importmap 不列该键，模块若 import 它
+	 * 则自行打包进模块产物（设计文档 §4.3 的「软共享缺席→模块自带副本兜底」语义）。
+	 * 用于**仅模块使用、宿主与共享 chunk 永不 import**的重型依赖（编辑器 / 图表 /
+	 * Markdown），避免把它们 5~6MB 的体量无谓铺进 shell-dist 并要求公开链路多传
+	 * 一堆文件。宿主侧有真实 import 的共享依赖（antd / pro-components / icons 内部
+	 * 依赖的 motion / react-jss / dayjs / zustand / @dnd-kit 等）绝不能标 bundle ——
+	 * 否则会被 antd 等共享 chunk 经 importmap 解析不到而 404。判定依据：宿主
+	 * host.tsx + runtime.js 的传递 import 图，以及 antd/pro-components/icons 的
+	 * 传递依赖图，都不含这些说明符。
+	 *
+	 * ⚠️ 本档位**不计入宿主版本一致性保障**：模块把副本打进产物，多副本不会报错，
+	 * 只会重复体积。体积怎么控，见 docs/devkit/manual.md §2.6。
 	 */
 	bundle?: boolean
 }
@@ -66,9 +71,10 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	 *   - 无单例语义。kit 必须唯一是因为多副本 = 两份 antd 上下文树；编辑器资产
 	 *     把 @tiptap/*、@plane/ui 等**全部内联**在自身里，跨边界穿过的只有 React
 	 *     家族（那是独立的硬共享条目），多一份编辑器副本不会拆散任何 context。
-	 *   - 不是每个模块都用编辑器。软共享的语义正是「默认由宿主提供，允许 importmap
-	 *     scopes 多版本共存兜底（C7）」——缺席时模块可自带副本而不硬失败。
-	 *     代价：多副本会重复约 5.4 MB 资产，故 scopes 只作兜底、默认仍走宿主。
+	 *   - 不是每个模块都用编辑器。软共享的语义是「允许缺席」——宿主**不预构建**
+	 *     这份资产（bundle: true，不进 shell-dist、不进 importmap），模块 import 它
+	 *     就自己打进产物。代价是每个用编辑器的模块各带一份约 5.4 MB，换来宿主
+	 *     分发体积不被没人用的重型依赖撑大。
 	 */
 	{ specifier: "@plane/editor", asset: "editor", hard: false, bundle: true },
 	// 注：@rc-component/form（antd 6 Form 底层）曾尝试单例化以修 my-profile
@@ -120,6 +126,9 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "dayjs/plugin/weekday", asset: "dayjs-plugin-weekday", hard: false },
 	{ specifier: "dayjs/plugin/weekOfYear", asset: "dayjs-plugin-weekOfYear", hard: false },
 	{ specifier: "dayjs/plugin/weekYear", asset: "dayjs-plugin-weekYear", hard: false },
+	// echarts 家族：模块自打包。整包 index（`import * as echarts from "echarts"`）会让
+	// 单个模块产物从 ~180KB 涨到 1.7MB（实测 echarts 918KB + zrender 221KB 占 87%），
+	// 故脚手架改用 `echarts/core` 按需注册；接入方写法见 docs/devkit/manual.md §2.6。
 	{ specifier: "echarts", asset: "echarts", hard: false, bundle: true },
 	{ specifier: "echarts/charts", asset: "echarts-charts", hard: false, bundle: true },
 	{ specifier: "echarts/features.js", asset: "echarts-features", hard: false, bundle: true },
@@ -147,18 +156,21 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "tailwind-merge", asset: "tailwind-merge", hard: false },
 	/**
 	 * Markdown 编辑器（Vditor v4，M5 回升自下游 oj-wiki）：npm 包是 webpack **UMD**
-	 * 单产物（main=dist/index.js，无 ESM 出口、仅 default 导出），走 starShim + esbuild
-	 * 的既有 CJS/UMD interop 链路打包成 ESM 资产（与 react 家族同路，无需新机制）。
+	 * 单产物（main=dist/index.js，无 ESM 出口、仅 default 导出）。bundle: true 表示
+	 * 宿主不预构建 —— CJS/UMD interop 交给模块自己的 rolldown 打包链路处理。
 	 *
-	 * 软共享：无单例语义（多副本只是重复体积，不拆 context），且不是每个模块都用。
-	 * 体积大（gzip ≈700 KiB），故**惰性生效**：importmap 只做映射，宿主 shell 自身
-	 * 不 import vditor ⇒ /assets/vditor.js 仅在模块产物真正 import 它时才被拉取，
-	 * 不进宿主首屏。
+	 * 为什么不预构建：体积大（gzip ≈700 KiB）且不是每个模块都用。宿主为它留一份
+	 * /assets/vditor.js，等于给所有站点无条件加 700 KiB 分发体积，而只有编辑器页
+	 * 才用得上。改由模块自带后，代价转给「真正 import 它的那个模块」。
+	 *
+	 * 副作用（写文档时容易说错）：模块产物是单文件（codeSplitting: false），
+	 * 所以 `import("vditor")` 会被内联回去，**动态导入并不能把它从首屏摘掉**；
+	 * 要省这笔体积只能把编辑器页拆成独立模块/方案。
 	 *
 	 * 深路径只登记 CSS 主样式（nprogress 同款样式垫片）。vditor 其余 dist 深路径
 	 * （lute / i18n / icons / 主题 CSS…）是**运行期经 cdn 选项按需拉取的资源**而非
 	 * import 说明符，由模块侧自行处理（自注入或指向宿主可服务的路径）；若模块代码
-	 * 直接 import 它们，会命中前缀 external 但无 importmap 键 → 构建期深路径报错，
+	 * 直接 import 它们，会命中前缀 external 但无共享表键 → 构建期深路径报错，
 	 * 属预期拦截（与 dayjs/plugin/* 同规则）。
 	 */
 	{ specifier: "vditor", asset: "vditor", hard: false, bundle: true },
@@ -182,6 +194,10 @@ export function generateShellEntries(): { name: string, pkg: string }[] {
 /**
  * 由共享表生成 importmap：说明符 → /assets/<asset>.js。
  * baseUrl 供宿主部署在子路径时使用。
+ *
+ * 注意：这里给出的是**逻辑名**。shell 构建落盘时会把每个资产改名成
+ * `<asset>.<hash>.js`（见 `hashedAssetFileName`），importmap 由构建脚本同步改写，
+ * 运行时拿到的仍是 `/assets/<asset>.<hash>.js`。
  */
 export function generateImportmap(baseUrl = ""): Record<string, string> {
 	const map: Record<string, string> = {};
@@ -196,3 +212,37 @@ export function generateImportmap(baseUrl = ""): Record<string, string> {
 export function isPrebuiltDep(id: string): boolean {
 	return SHARED_DEPS.some(dep => !dep.bundle && (id === dep.specifier || id.startsWith(`${dep.specifier}/`)));
 }
+
+/**
+ * 共享资产的内容哈希段：10 位 base36，且**保证**同时含数字与字母。
+ *
+ * 为什么必须保证：oj serve ≥ 0.1.116 的默认缓存策略按**文件名**判定
+ * （`serve/src/static_files.rs::default_cache_control`）——文件名 stem 按 `-` `_` `.`
+ * 切段，末段 ≥8 位且同时含数字与字母才发 `public, max-age=31536000, immutable`，
+ * 其余一律 `no-cache`。纯 base36 有十万分之一量级会全数字（vite 的 base64url 更糟：
+ * 8 位全字母约 19%），漏判就白丢一年缓存。这里按「缺哪类补哪类」定长补齐，
+ * 让每个资产 100% 命中长缓存，而不是赌概率。
+ *
+ * 9 位 base36 ≈ 46.5 bit，65 个资产量级碰撞概率可忽略。
+ */
+export function assetHash(content: string | Uint8Array): string {
+	const digest = createHash("sha256").update(content).digest();
+	const body = digest.readBigUInt64BE(0).toString(36).slice(0, 9).padStart(9, "0");
+	// 已有字母 → 补数字；全数字 → 补字母。两类必在其一，补齐另一类即可。
+	return /[a-z]/.test(body) ? `${body}0` : `${body}z`;
+}
+
+/** 内容寻址文件名：`<base>.<hash>.js`（js 与 map 同为 .js 后缀，map 保持原名不动） */
+export function hashedAssetFileName(base: string, content: string | Uint8Array): string {
+	return `${base}.${assetHash(content)}.js`;
+}
+
+/**
+ * 与 oj serve 的 `default_cache_control` 同口径：末段 ≥8 位且数字字母都有 → 可发 immutable。
+ * 构建期用它断言产物名，避免哪天哈希算法换掉后长缓存静默失效。
+ */
+export function isImmutableAssetFileName(fileName: string): boolean {
+	const stem = fileName.replace(/\.[^.]*$/, "");
+	const seg = stem.split(/[-_.]/).pop() ?? "";
+	return seg.length >= 8 && /\d/.test(seg) && /[a-z]/i.test(seg);
+}

package/src/site-base.ts

@@ -102,6 +102,10 @@ export function rewriteIndexHtml(html: string, siteBase: string | undefined, api
 		// 上一步已处理，二者不重叠。
 		out = out.replace(/(\b(?:href|src|data-ojm-entry)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
 			`${attr}${withSiteBase(url, base)}`);
+		// data-ojm-preload 是**逗号分隔的 URL 列表**（构建期算好的首屏静态闭包），
+		// 上面那条单值正则匹配不到列表，漏改会让子路径部署下预取全 404（退化回瀑布，不白屏但慢）
+		out = out.replace(/(\bdata-ojm-preload=")([^"]*)"/g, (_m, attr: string, list: string) =>
+			`${attr}${list.split(",").map(url => url.startsWith("/") ? withSiteBase(url, base) : url).join(",")}"`);
 		globals.push(`window.__OJ_BASE__=${JSON.stringify(base)};`);
 	}
 	if (api) {

package/templates/src/app/web/home/pages/components/bar-chart.tsx

@@ -1,9 +1,11 @@
 import type { EChartsOption } from "echarts";
 import { Card } from "antd";
-import ReactECharts from "echarts-for-react";
+import ReactEChartsCore from "echarts-for-react/esm/core";
 import { useTranslation } from "react-i18next";
 
-/** 柱状图：演示 `echarts` + `echarts-for-react`（共享依赖，宿主 importmap 提供）。 */
+import { echarts } from "./echarts-setup";
+
+/** 柱状图：按需注册的 `echarts` + `echarts-for-react/esm/core`（见 echarts-setup.ts）。 */
 export default function BarChart() {
 	const { t } = useTranslation();
 	const categories = [
@@ -25,7 +27,7 @@ export default function BarChart() {
 	};
 	return (
 		<Card title={t("home:views")}>
-			<ReactECharts opts={{ height: 320, width: "auto" }} option={option} />
+			<ReactEChartsCore echarts={echarts} opts={{ height: 320, width: "auto" }} option={option} />
 		</Card>
 	);
 }

package/templates/src/app/web/home/pages/components/echarts-setup.ts

@@ -0,0 +1,30 @@
+/**
+ * 按需注册的 echarts 实例（体积治理）。
+ *
+ * 为什么不用 `import ReactECharts from "echarts-for-react"`：
+ * 那条路径会 `import * as echarts from "echarts"`（整包 index），把 **全部图表类型 +
+ * 全部组件 + 全部渲染器** 打进模块产物。实测 `app` 模块 entry.js 1,697,666 B 中
+ * echarts 918 KB + zrender 221 KB，占 **87%**；而首页只用到折线/柱状/饼图三种。
+ *
+ * 这里改用 `echarts/core` 按需注册：只留 3 种图表 + 3 个组件 + Canvas 渲染器，
+ * 同一份代码实测 1,125 KB → 572 KB（−49%）。
+ *
+ * 新图表类型/组件时，务必在这里 `use()` 补上——否则运行期渲染为空且**不报错**，
+ * 是最常见的 echarts 按需踩坑。
+ */
+import { BarChart, LineChart, PieChart } from "echarts/charts";
+import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
+import * as echarts from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+
+echarts.use([
+	BarChart,
+	LineChart,
+	PieChart,
+	GridComponent,
+	LegendComponent,
+	TooltipComponent,
+	CanvasRenderer,
+]);
+
+export { echarts };

package/templates/src/app/web/home/pages/components/line-chart.tsx

@@ -1,12 +1,14 @@
 import type { EChartsOption } from "echarts";
 import { Card, Radio } from "antd";
 import dayjs from "dayjs";
-import ReactECharts from "echarts-for-react";
+import ReactEChartsCore from "echarts-for-react/esm/core";
 import { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 
+import { echarts } from "./echarts-setup";
+
 /**
- * 折线图：演示 `echarts` + `echarts-for-react` + `dayjs`（共享依赖）。
+ * 折线图：按需注册的 `echarts` + `echarts-for-react/esm/core`（见 echarts-setup.ts）。
  * 数据为静态演示值——真实业务请走模块契约 + `ojm api` 生成的 client
  * （参考 `demo` 模块的裸 fetch 与教程里 books 模块的契约式接法）。
  */
@@ -69,7 +71,7 @@ export default function LineChart() {
 				</Radio.Group>
 			)}
 		>
-			<ReactECharts opts={{ height: 320, width: "auto" }} option={option} />
+			<ReactEChartsCore echarts={echarts} opts={{ height: 320, width: "auto" }} option={option} />
 		</Card>
 	);
 }

package/templates/src/app/web/home/pages/components/pie-chart.tsx

@@ -1,11 +1,14 @@
 import type { EChartsOption } from "echarts";
 import { Card, Segmented } from "antd";
-import ReactECharts from "echarts-for-react";
+import ReactEChartsCore from "echarts-for-react/esm/core";
 import { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 
+import { echarts } from "./echarts-setup";
+
 /**
- * 饼图：演示 `echarts` + `echarts-for-react` + antd `Segmented` 联动。
+ * 饼图：按需注册的 `echarts` + `echarts-for-react/esm/core` + antd `Segmented` 联动
+ * （注册清单见 echarts-setup.ts）。
  * 数据为静态演示值（各渠道 × 品类）。
  */
 const VALUES: Record<string, number[]> = {
@@ -59,7 +62,7 @@ export default function PieChart() {
 				/>
 			)}
 		>
-			<ReactECharts opts={{ height: 320, width: "auto" }} option={option} />
+			<ReactEChartsCore echarts={echarts} opts={{ height: 320, width: "auto" }} option={option} />
 		</Card>
 	);
 }

package/templates/src/app/web/home/pages/index.tsx

@@ -19,8 +19,9 @@ const wrapperCol: ColProps = {
 
 /**
  * 首页：结构对齐 playground home，用自带的统计卡片与三类图表
- * 演示宿主共享依赖矩阵（echarts / echarts-for-react / react-countup / dayjs /
- * antd / @ant-design/icons / react-i18next 均由宿主 importmap 单例提供）。
+ * 演示依赖矩阵（react-countup / dayjs / antd / @ant-design/icons / react-i18next
+ * 由宿主 importmap 单例提供；echarts 由模块自打包并按需注册，
+ * 见 `./components/echarts-setup.ts`）。
  */
 export default function HomePage() {
 	return (

package/templates/src/app/web/home/routes.ts

@@ -14,8 +14,9 @@ const Home = lazy(() => import("./pages/index"));
  * 工程缺 `/home` 路由时这些跳转会落到错误边界。
  *
  * 结构对齐 playground-oj/web/src/home；页面用统计卡片 + 折线/柱/饼图
- * 演示宿主共享依赖矩阵（echarts / echarts-for-react / react-countup / dayjs /
- * antd / @ant-design/icons / react-i18next，均由宿主 importmap 提供单例）。
+ * 演示依赖矩阵（react-countup / dayjs / antd / @ant-design/icons / react-i18next
+ * 由宿主 importmap 提供单例；echarts 属模块自打包的重型依赖，走按需注册，
+ * 见 `pages/components/echarts-setup.ts`）。
  * 图表数据为静态演示值——真实业务走模块契约 + `ojm api` 生成的 client。
  */
 export const routes: AppRouteRecordRaw[] = [

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.64",
-		"@oj-module/runtime/contract": "0.2.64",
-		"@oj-module/runtime/contract/errors": "0.2.64",
+		"@oj-module/runtime": "0.2.66",
+		"@oj-module/runtime/contract": "0.2.66",
+		"@oj-module/runtime/contract/errors": "0.2.66",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",