Files
funjia 21d293775d feat(plugin): 产物自带样式 —— 第三方只取 entry 也能正常显示
第三方系统装完后样式全丢。复现出来的根因是产物形态:CSS 被抽成独立文件,
仓库契约要求消费方自己读 `style` 并注入 <link>(文档写了、官方参考消费方也照做了),
但第三方很容易只取 `entry`:插件能跑、页面却是白板(布局全靠 CSS)。
实测:只取 entry 时文档里插件样式表数量 0,.pt-panel 宽度从 356px 变成撑满的 1368px。

改法:vite.config.ts 新增 selfInjectStyles() 插件,在 generateBundle 阶段
把抽出的 CSS 内联进 JS,脚本一加载就注入 <style data-funjia-plugin=…>。

- 保留 style 字段与 CSS 文件不变:按文档注入的宿主照常工作;CSP 禁止内联样式时
  那条路仍是唯一出路。
- 不重复注入:先检测有没有本插件的 <style data-funjia-plugin=…>,
  或 href 指向本样式文件的 <link>,有就跳过。
- 走 generateBundle 而非「写完盘再改」:后者注入发生在 vite 打印体积之后,
  日志 98KB / 索引 109KB 对不上账。
- 拿不到 CSS 资源时 this.warn 显式报出,不静默少注入。
- verify.mjs 加断言盯着它(产物必须含注入器)。

验证:第三方最小消费方 4 项断言全过;宿主路径 4 项全过(CSS 恰好一份、无重复注入);
对已发布产物跑 13 项打印断言全过。产物已发布为 funjia.print-tag@1.0.3。

注意:本工程从此不再等同于 funjia-plugin-starter 的默认产物形态 ——
其他插件若也会被第三方接入,值得把这套 self-inject 搬过去。
2026-10-04 01:32:14 +08:00

188 lines
8.4 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 插件构建配置(一个工程 = 一个插件)。
*
* ## 唯一的真源是 `plugin.config.json`
*
* 产物文件名、IIFE 全局名、格式(IIFE / ESM)全部从这里读 —— 不在这里写第二遍。
* 理由很实际:这几个值**必须**与「发布到仓库时那条 `repo.config.json` 条目」
* 完全一致(`artifact` 对不上 → 发布脚本找不到产物;`globalKey` 对不上 →
* 脚本加载成功但宿主认领不到插件)。让它们只有一个来源,就不会对不上。
*
* ## 依赖共享的规矩(别改,除非你知道后果)
*
* `vue` 与 `funjiaui` **必须 external**,由宿主提供:
*
* - IIFE:靠 `output.globals` 映射到 `window.vue` / `window.funjiaui`;
* - ESM:`output.globals` 对 ESM 无效(rollup 会忽略),产物里保留裸说明符
* `from "vue"`,由宿主的 import map 解析;宿主还有一条不依赖 import map 的
* 兜底通道,所以你不需要为此做任何事。
*
* 为什么必须共享 `vue`:插件与宿主各打一份 Vue,会导致**两份响应式系统互相不认**,
* 症状是「页面渲染出来了、但完全点不动」。这是最容易踩、也最难看懂的一个坑。
*
* 其它依赖(element-plus、lodash、图表库…)**不要 external**,让它们打进产物。
* 插件体积大一点没关系,宿主不必为了插件把整个组件库挂到全局。
*/
import { defineConfig, type Plugin } from "vite";
import vue from "@vitejs/plugin-vue";
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
const root = __dirname;
const cfg = JSON.parse(readFileSync(resolve(root, "plugin.config.json"), "utf8"));
const FORMAT = cfg.kind === "esm" ? "es" : "iife";
/**
* IIFE 需要 `lib.name`(rollup 用它生成 `var <name> = …`)。
*
* - 走 `window.<globalKey>` 通道的插件:必须与 `globalKey` 一致;
* - 走 `window.FunjiaPlugin.register()` 自注册通道的插件:这个名字不影响认领,
* 但仍然要是合法标识符(rollup 会直接把它写进代码)。
*/
const GLOBAL_NAME = cfg.globalKey || cfg.id.replace(/[^A-Za-z0-9_$]/g, "_");
if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(GLOBAL_NAME)) {
throw new Error(
`plugin.config.json 的 globalKey 不合法:${JSON.stringify(GLOBAL_NAME)}\n` +
"它会被写进产物当全局变量名,必须以字母 / _ / $ 开头,其后只含字母、数字、_、$。"
);
}
if (!/^[A-Za-z0-9_.-]+\.(iife|es)\.js$/.test(cfg.artifact)) {
throw new Error(
`plugin.config.json 的 artifact 不合法:${JSON.stringify(cfg.artifact)}\n` +
'它同时是产物文件名与仓库索引里的 artifact 字段,形状应为 "<Name>.iife.js" 或 "<Name>.es.js"。'
);
}
/** 与宿主 `installHostGlobals()` 挂的全局严格对应 */
const HOST_GLOBALS: Record<string, string> = {
vue: "vue",
funjiaui: "funjiaui",
};
/* ------------------------------------------------------------------ *
* 让产物「自带样式」
* ------------------------------------------------------------------ */
/** 注入器的哨兵注释:重复构建时先按它把旧的剥掉,避免 watch 下越叠越多 */
const INJECTOR_SENTINEL = "/* funjia:self-inject-styles */";
/**
* 把抽出来的 CSS 内联进 JS,脚本一加载就把样式注入文档。
*
* ## 为什么必须这么做
*
* 仓库契约里 `style` 是**独立字段**:消费方要自己读它、注入 `<link>`。文档写清楚了,
* 官方参考消费方(`repo-consumer.html`)也照做了 —— 但**第三方很容易只取 `entry`**,
* 于是插件能跑、页面却是白板(所有布局都靠 CSS,样式没了等于不可用)。
* 实测过:只用 `entry` 时文档里插件样式表数量是 0,`.pt-panel` 的宽度从 356px
* 变成撑满的 1368px。
*
* 一个「交付物」不该依赖消费方记得做第二步。所以产物自带样式:
*
* - 保留 `style` 字段与那个 CSS 文件**不变** —— 按文档注入的宿主照常工作,
* 也便于审计;CSP 禁止内联样式时,那条路是唯一出路。
* - 同时在 JS 里挂一个注入器兜底。两处都生效时**不会重复注入**:注入器会先看
* 文档里有没有本插件的 `<style data-funjia-plugin=…>`,或有没有 href 指向
* 本样式文件的 `<link>`,有就跳过。
*
* ## 为什么走 generateBundle(而不是写完盘再改文件)
*
* 「写完盘再读改」更简单,但构建日志报的体积会**不含**注入进去的那份 CSS
* (注入发生在 vite 打印体积之后),于是日志 98KB、仓库索引 109KB,
* 对不上账、还得每次解释。走 `generateBundle` 是在产物落盘之前改代码,
* 体积、checksum、日志三者天然一致。
*
* `enforce: "post"` 是必需的:CSS 资源由 Vite 内置的 css-post 插件在
* generateBundle 阶段产生,我们的钩子必须排在它之后才拿得到。
* 万一没拿到,`this.warn` 会在构建日志里**显式报出来** —— 而不是静默少注入一份样式
* (那正是这个函数要解决的问题本身)。
*/
function selfInjectStyles(): Plugin {
const styleFile = cfg.style as string | undefined;
if (!styleFile) return { name: "funjia:self-inject-styles" };
return {
name: "funjia:self-inject-styles",
apply: "build",
enforce: "post",
generateBundle(_options, bundle) {
const cssAsset = Object.values(bundle).find(
(item) => item.type === "asset" && item.fileName === styleFile
);
const entryChunk = Object.values(bundle).find(
(item) => item.type === "chunk" && item.isEntry
);
if (!cssAsset || !entryChunk) {
this.warn(
`自带样式注入被跳过:${!cssAsset ? `产物里没有 ${styleFile}` : "找不到入口 chunk"}。` +
`这通常意味着样式提取插件没跑或产物名对不上 —— ` +
`插件仍可用,但消费方漏注入 style 时页面会没有样式。`
);
return;
}
const css = typeof cssAsset.source === "string" ? cssAsset.source : String(cssAsset.source);
const injector =
`${INJECTOR_SENTINEL}\n` +
`(function(){` +
`var ID=${JSON.stringify(cfg.id)},FILE=${JSON.stringify(styleFile)};` +
// 宿主已经按 manifest.style 注入了 → 不重复注入(省一份 ~10KB 的重复 CSS)
`var links=document.querySelectorAll('link[rel="stylesheet"]');` +
`for(var i=0;i<links.length;i++){` +
`if((links[i].getAttribute("href")||"").indexOf(FILE)!==-1)return;}` +
`if(document.querySelector('style[data-funjia-plugin="'+ID+'"]'))return;` +
`var s=document.createElement("style");` +
`s.setAttribute("data-funjia-plugin",ID);` +
`s.textContent=${JSON.stringify(css)};` +
`(document.head||document.documentElement).appendChild(s);` +
`})();\n`;
// 幂等:watch 模式下同一轮可能重复经过这里,先按哨兵剥掉旧的
let code = entryChunk.code;
if (code.startsWith(INJECTOR_SENTINEL)) {
const end = code.indexOf("\n", code.indexOf("})();"));
code = end >= 0 ? code.slice(end + 1) : code;
}
entryChunk.code = injector + code;
},
};
}
export default defineConfig({
root,
plugins: [vue(), selfInjectStyles()],
build: {
target: "es2015",
outDir: resolve(root, "dist"),
// 一个工程只有一个插件,可以放心清空 —— 避免上一版的陈旧产物被误发布
emptyOutDir: true,
// 样式不拆成多份:宿主按 manifest.style 注入**一个**文件,拆了会漏注入
cssCodeSplit: false,
sourcemap: false,
lib: {
entry: resolve(root, "src/index.ts"),
name: GLOBAL_NAME,
formats: [FORMAT],
// 产物名直接取自 plugin.config.json —— 与仓库索引里的 artifact 天然一致
fileName: () => cfg.artifact,
},
rollupOptions: {
external: Object.keys(HOST_GLOBALS),
output: {
globals: HOST_GLOBALS,
assetFileNames: cfg.style || `${GLOBAL_NAME}[extname]`,
// ⚠️ 不能省:否则「导出被 rollup 判成 namespace」时,
// 产物会变成 `window.X = { default: class {} }`,宿主拿到后
// **不报错、但页面渲染不出任何东西** —— 最难查的一类静默失败。
...(FORMAT === "iife" ? { exports: "default" as const } : {}),
},
},
},
});