如何为 Shiki 打造专属主题?TextMate 主题格式与自定义配色完全指南
如何为 Shiki 打造专属主题?TextMate 主题格式与自定义配色完全指南
Shiki 是一款被称为"漂亮且强大"的代码语法高亮工具,而本文正是为新手准备的 Shiki 自定义主题完整指南:无需了解复杂源码,只要掌握 TextMate 主题格式,你就能用几十行配置打造属于自己的代码高亮配色方案,并通过 colorReplacements、CSS 变量等手段快速换肤、支持明暗双主题。
一、为什么需要"专属 Shiki 主题"?
Shiki 内置了上百个常用主题(如 nord、catppuccin-mocha、vitesse-dark),但它们并不总能匹配你的品牌色或站点风格。打造专属主题的价值在于:
- 🎨 品牌一致性:让代码块颜色与你的网站设计语言统一
- 🌗 明暗双主题:一套代码,自动适配深色/浅色模式
- ⚡ 按需裁剪:主题以按需加载方式注册,不用的主题零成本
内置主题列表及来源可参考 docs/themes.md,主题对象的标准类型定义在 packages/types/src/themes.ts。
二、快速上手:三步加载自定义 Shiki 主题
官方文档 docs/guide/load-theme.md 给出了一条最简路径,三步即可跑通:
第 1 步:写出一个最小主题对象
Shiki 的主题本质上就是一个 TextMate 主题 JSON 对象,核心是 name(主题名)+ settings(逐条配色规则):
const myTheme = {
name: 'my-theme',
type: 'dark',
settings: [
{ scope: ['comment'], settings: { foreground: '#888' } },
{ scope: ['string'], settings: { foreground: '#9c9' } },
// 继续添加更多规则……
],
}
第 2 步:把主题注册进 Shiki
将对象直接传入 themes 数组,创建高亮器后即可用主题名渲染:
const highlighter = await createHighlighter({
themes: [myTheme],
langs: ['javascript'],
})
const html = highlighter.codeToHtml(code, { lang: 'javascript', theme: 'my-theme' })
第 3 步:也可以"事后加载"
主题还可以从文件、网络请求中读取后,通过 highlighter.loadTheme(myTheme) 动态注册(详见 docs/guide/load-theme.md),非常适合"用户自选主题"之类的场景。
三、TextMate 主题格式详解:核心字段清单
一份完整的 TextMate 主题包含哪些字段?Shiki 的解析逻辑位于 packages/primitive/src/textmate/normalize-theme.ts,对照下表即可手写主题:
| 字段 | 作用 | 说明 |
|---|---|---|
name |
主题唯一标识 | 高亮时通过它引用,如 'my-theme' |
displayName |
展示名称 | 可选,用于 UI 展示 |
type |
明暗类型 | 'light' 或 'dark',影响默认前后景色 |
settings |
配色规则数组 | 每条含 scope(作用域)+ settings.foreground/background |
tokenColors |
兼容字段 | 老式 VS Code 主题写法,效果等同 settings |
colors |
编辑器级颜色 | 如 editor.foreground,用于推断默认前后景与 ANSI 配色 |
几个新手友好的细节:
scope决定"给谁上色":如comment(注释)、string(字符串)、keyword(关键字)。一条规则可写多个作用域,匹配到哪个词法标记就生效。- 省略颜色会自动兜底:若主题没写
fg/bg,Shiki 会依次尝试全局settings、colors<a href="https://link.gitcode.com/i/58090e3214efcd00ac0cd26992cb6a73" target="_blank">'editor.foreground'],最后回退到 VS Code 风格默认值(深色底#1e1e1e),见 [normalize-theme.ts。 - 不想上色? 把
theme设为'none'可完全跳过高亮,适合作为用户指定了未知主题时的兜底(见 docs/themes.md)。
四、进阶玩法:三种"偷懒"的自定义配色方式
写满几十条 settings 太累?Shiki 提供了三种省力路线,详见 docs/guide/theme-colors.md。
4.1 任意颜色值:直接写 RGB 和 CSS 变量
TextMate 原生只认十六进制色值,但 Shiki 会自动把非十六进制颜色替换为占位符、渲染时再还原。因此你可以直接写:
{ scope: ['comment'], settings: { foreground: 'rgb(128,128,128)' } }
{ scope: ['string'], settings: { foreground: 'var(--code-string)' } }
rgb、hsl、甚至 CSS 变量 var(--xxx) 都支持,主题配色可以直接跟随你的设计系统。注意:这样写出的主题与 TextMate 生态不完全兼容,可能无法用于 CLI 等非 Web 场景。
4.2 colorReplacements:给现有主题一键换色
不想从零写主题?拿一个内置主题,再用**"旧色值 → 新色值"**的映射批量替换即可:
const html = await codeToHtml(code, {
lang: 'js',
theme: 'min-dark',
colorReplacements: { '#ff79c6': '#189eff' },
})
双主题场景下还能按主题名分组替换(如 'min-dark' 和 'min-light' 各换一套色),实现"一个主题、两套品牌色"。
4.3 createCssVariablesTheme:CSS 变量主题工厂
如果你希望颜色完全由站点 CSS 控制,可以用 shiki/core 提供的工厂函数一行生成主题:
const myTheme = createCssVariablesTheme({
name: 'css-variables',
variablePrefix: '--shiki-',
})
随后在站点 :root 中定义 --shiki-token-string、--shiki-token-keyword 等变量即可。注意该主题粒度较粗,追求精细高亮效果时,推荐 4.1 的手工方式(变量清单见 docs/guide/theme-colors.md)。
4.4 顺手解锁:明暗双主题输出
把 codeToHtml 的 theme 选项换成 themes: { light: ..., dark: ... },Shiki 会把两套颜色以 CSS 变量形式写进每个 token,再配合一小段媒体查询 CSS,就能实现"深/浅色自动切换",完整做法见 docs/guide/dual-themes.md。
五、内置主题从哪来?
Shiki 内置主题统一再分发自社区的 tm-themes 仓库,构建脚本 packages/themes/scripts/themes.ts 会把每个主题的 JSON 打包成独立 ES 模块,按需动态加载。这也意味着:你手写的 TextMate 主题与内置主题在格式上完全一致——照着 tm-themes 里的 dark-plus.json 等示例抄结构,是最快的入门方式。
六、新手避坑小贴士
- 主题名全局唯一:
codeToHtml里theme字段填的就是name,写错会直接报"主题未加载"。 - 记得声明
type:不写默认按'dark'处理,浅色主题请显式标注'light',否则兜底色会错。 settings第一条留空作用域可设默认色:Shiki 自动插入的兜底规则就是"无 scope + 前后景色",你手写主题时同样可用这个技巧设定全局默认。createHighlighter实例要长驻复用:主题注册后常驻在实例里,避免在循环中反复创建高亮器。- 非 Web 渲染慎用任意色值:
rgb()、CSS 变量等写法在 shiki-cli 等场景中可能失效,保持十六进制最稳妥。
七、结语:你的专属 Shiki 主题只需一次动手
总结一下最短路径:照 TextMate 格式写出 name + settings → 塞进 themes 数组 → codeToHtml 引用主题名。再按需叠加 colorReplacements 换色、CSS 变量主题、明暗双主题三个进阶能力,一个品牌级代码配色方案就完成了。相关入口文档:docs/guide/load-theme.md、docs/guide/theme-colors.md、docs/guide/dual-themes.md。
