Shiki高亮引擎中自定义主题与语言加载的注意事项

在使用Shiki代码高亮引擎时，开发者可能会遇到一个常见问题：当切换到自定义主题后，原先可用的语言高亮功能突然失效。这种现象背后反映了Shiki引擎从1.0版本开始的一项重要架构变更。

核心机制解析

在Shiki的早期版本中，引擎默认会加载所有支持的语言包。但在1.0版本后，出于性能优化的考虑，Shiki改为按需加载机制。这意味着：

1. 显式声明原则：所有需要使用的语言都必须明确声明
2. 资源隔离：主题加载和语言加载成为两个独立的配置维度
3. 按需加载：只加载实际需要的语言资源，减少初始包体积

典型问题场景

开发者从文档中复制自定义主题示例时，常忽略语言配置项：

const highlighter = await getHighlighter({
  themes: [myTheme] // 仅配置主题，未声明语言
});

此时尝试高亮JavaScript代码就会触发Language not found错误，因为引擎没有加载任何语言支持。

解决方案

方案一：完整加载（适合开发环境）

import { bundledLanguages, getHighlighter } from 'shiki';

const highlighter = await getHighlighter({
  themes: [myTheme],
  langs: Object.keys(bundledLanguages) // 加载所有语言
});

方案二：按需加载（适合生产环境）

const highlighter = await getHighlighter({
  themes: [myTheme],
  langs: ['javascript', 'typescript'] // 仅加载必要语言
});

方案三：Node环境快捷方式

在Node.js运行时环境下，可以使用自动化加载的简写形式：

const highlighter = await getHighlighter({
  theme: 'nord' // 自动加载对应语言
});

最佳实践建议

1. 开发阶段可以使用完整加载模式快速验证
2. 生产环境建议精确声明需要的语言
3. 自定义主题时务必同步考虑语言依赖
4. 对于SSR应用，注意服务端和客户端的语言包一致性

理解这一机制后，开发者就能更好地平衡功能完整性和性能优化，充分发挥Shiki的高亮能力。