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 搬过去。
This commit is contained in:
2026-10-04 01:32:14 +08:00
parent a049492864
commit 21d293775d
4 changed files with 151 additions and 4 deletions
+93 -2
View File
@@ -24,7 +24,7 @@
* 插件体积大一点没关系,宿主不必为了插件把整个组件库挂到全局。
*/
import { defineConfig } from "vite";
import { defineConfig, type Plugin } from "vite";
import vue from "@vitejs/plugin-vue";
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
@@ -63,9 +63,100 @@ const HOST_GLOBALS: Record<string, string> = {
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()],
plugins: [vue(), selfInjectStyles()],
build: {
target: "es2015",
outDir: resolve(root, "dist"),