如何为 Shiki 打造专属主题?TextMate 主题格式与自定义配色完全指南

原创2026-09-21 23:19:001,715 阅读
文章标签:前端开发工具

如何为 Shiki 打造专属主题?TextMate 主题格式与自定义配色完全指南

Shiki 是一款被称为"漂亮且强大"的代码语法高亮工具,而本文正是为新手准备的 Shiki 自定义主题完整指南:无需了解复杂源码,只要掌握 TextMate 主题格式,你就能用几十行配置打造属于自己的代码高亮配色方案,并通过 colorReplacements、CSS 变量等手段快速换肤、支持明暗双主题。

Shiki 代码高亮工具与 TextMate 主题自定义配色预览

一、为什么需要"专属 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 等示例抄结构,是最快的入门方式。

六、新手避坑小贴士

  1. 主题名全局唯一:codeToHtml 里 theme 字段填的就是 name,写错会直接报"主题未加载"。
  2. 记得声明 type:不写默认按 'dark' 处理,浅色主题请显式标注 'light',否则兜底色会错。
  3. settings 第一条留空作用域可设默认色:Shiki 自动插入的兜底规则就是"无 scope + 前后景色",你手写主题时同样可用这个技巧设定全局默认。
  4. createHighlighter 实例要长驻复用:主题注册后常驻在实例里,避免在循环中反复创建高亮器。
  5. 非 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。

登录后查看全文
shiki