Skip to content
yijiu2025 edited this page Oct 25, 2026 · 1 revision

FAQ(常见问题速查)

完整版在文档站「常见坑」——每一条都真实踩过。本页收录问得最多的几条。

加了主题没生效?

第一件事核白名单正则:/^[a-z0-9-]+$/——目录名大写、下划线、中文都会静默跳过(dev 下有 [theme] 扫描跳过 … 警告)。再查 VITE_THEME_DIR 是否指向存在的目录、store 文件是否 import 'virtual:theme'。

为什么换版式要新建主题包?

设计定案:一个主题包 = 一种版式。页面下没有「版式」这层目录——曾支持过 <页面>/<版式>/colors/,但换版式要复制整套配色,两套必然漂移,已删除。换版式 = 新建包(如 themes/compact/…)。

设备(mobile / standard / mini)是库定义的吗?

不是。设备词汇、判定口径(视口 / UA / ?device=)、容器布线全是宿主事实;库自 0.9 起不持有设备注册表与布线工具。库只消费两样:createThemeState({ devices }) 注入的词汇 + <ThemeView device> props。oauth21 的机制层在它的 src/device/(createDeviceModule / pageContainers)——那些不是 skinsuite 的导出。

?th=compat(拼错)为什么不报错?

契约是「非法值不回退」:pick() 落当前包,页面照常渲染——静默失败不锁死页面是刻意的。dev 下 console 有 [theme] 警告(无门控恒开);?debug=theme 时探针 window.__MAUTH_STORE__.warnings 能看到完整判定。

tokens 为什么不支持 url() 和颜色名?

CSS 自定义属性能直接改变渲染:url() 是外发请求的唯一入口(探测/追踪),颜色名上百个白名单易漏且会连带放行历史攻击向量。必须写 url() / 伪元素 / keyframes 的走 theme.scss(构建期受信代码)。

^0.11.0 会自动跟 minor 吗?

不会——0.x 下 caret 不跨 minor(>=0.11.0 <0.12.0),每发一个 minor 要手工跟版。这是 0.x 允许重命名导出的固有成本。见 Versioning。

微前端 / 同源多应用会互相干扰吗?

会——注册表与清单是模块级单例,token 注入写 document.documentElement。承诺形态:每个 JS realm + 每份 document = 一个主题域。子应用要么模块隔离,要么只用纯内核自管注入;同源多应用用 storageKeys / colorParam / viewParam 细分键名。

skinsuite Wiki

外部

Clone this wiki locally