构建插件 skinsuite/vite
以编译产物发布(dist/vite/index.js),类型直供源码。vite.config.ts 一行接入:
ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { themeAssets } from 'skinsuite/vite';
export default defineConfig({
// 目录缺省 = env VITE_THEME_DIR(含 .env.<mode>/.env.local/CLI 分层),无 env 则 src/theme
plugins: [themeAssets(), vue()]
});themeAssets(options?)
| 选项 | 缺省 | 说明 |
|---|---|---|
dir | env VITE_THEME_DIR → src/theme | 主题根目录(相对 Vite root 或绝对路径)。省略时插件在 configResolved 用 Vite 已加载的 env 自解析——无 process.cwd() 陷阱 |
moduleId | 'virtual:theme' | 虚拟模块 id |
manifestFile | 'theme.config.ts' | 清单文件名;设空串则不注入清单 |
vue | true | 是否装配 Vue 绑定层(themeViews/themeParts 加载表 + installThemeViews/installThemeParts)。纯 React / Node 宿主传 false,避免被迫加载 Vue 运行时(内核零框架耦合) |
插件行为
- 扫描(构建期,Node 侧 fs):
dir/themes/<包>/<设备>/<页面>/{index.vue, colors/<配色>/{index.ts, theme.scss}}+parts/<部件id>/+dir/views/*.ts声明; - 产出虚拟模块:三张资产表 +
themeViews/themeParts加载表 + 清单;import 副作用自动完成全部装配(installThemeViews/installThemeParts/installThemeRegistry/installThemeManifest+ 声明文件拉齐)——宿主无需 importvirtual:theme之外的任何声明; - fail-soft:目录不存在 → 空注册表 + 空清单(应用照常起);写歪条目跳过,dev(serve)下
[theme] 扫描跳过 <路径>:<原因>去重警告,构建期零噪音。唯独清单写错不跳过——defineThemeManifest启动即抛; - HMR:主题目录在 root 外也会
watcher.add;监听 add / unlink / addDir / unlinkDir 四事件(路径归一比较 + 前缀带分隔符),失效虚拟模块 + full-reload;改已有文件内容由普通模块 HMR 自己处理。
virtual:theme 的形态
ts
declare module 'virtual:theme' {
export const packages: Record<string, { default: MauthThemePackage }>;
export const colors: Record<string, { default: MauthThemeColor }>;
export const styles: Record<string, () => Promise<string>>; // ?inline 惰性
export const themeViews: Record<string, Record<string, Loader>>; // 按页面分组
export const themeParts: Record<string, Record<string, Loader>>; // 按部件 id 分组
export const themeManifest: ResolvedThemeManifest; // 恒非 null
type Loader = () => { default: unknown } | Promise<{ default: unknown }>; // 组件类型由 vue 层自行收窄
}- 资产键相对
themes/(./<包>/...开头); - 内置包(
default)的加载器同步返回模块命名空间(eager 静态 import,首帧零请求);其余包惰性import()chunk; - 类型声明随包发布,宿主
vite-env.d.ts里import "skinsuite/vite";带入程序(不要用/// <reference types>——解析不到子路径入口,报 TS2882)。
目录常量
| 导出 | 值 | 说明 |
|---|---|---|
DEFAULT_THEME_DIR | 'src/theme' | 缺省主题根目录(CI 与独立克隆无 .env 时仍能构建) |
THEME_DIR_ENV_KEY | 'VITE_THEME_DIR' | env 键名(单一来源) |
THEME_PACKAGES_SUBDIR | 'themes' | 主题包子目录名(固定约定) |
THEME_VIEWS_SUBDIR | 'views' | 页面契约子目录名(固定约定) |
DEFAULT_THEME_MANIFEST | 'theme.config.ts' | 清单文件名 |
与单测共用
构建与单测两侧必须用同一份插件(否则单测的 virtual:theme 是空表,用例静默落默认值)。首选 vitest 的 mergeConfig(viteConfig, …) 继承(插件只在 vite.config 声明一次);零参后没有可漂移的参数。