Shiki同步使用指南：深入解析createHighlighterCoreSync

Shiki同步使用指南：深入解析createHighlighterCoreSync

shiki A beautiful Syntax Highlighter. 项目地址: https://gitcode.com/gh_mirrors/sh/shiki

同步与异步处理的本质区别

在现代JavaScript开发中，异步操作已经成为常态。Shiki作为一个语法高亮库，其核心功能需要加载语言定义和主题配置等资源，这些操作通常都是异步的。但在某些特殊场景下，开发者可能需要完全同步的执行流程。

为什么需要同步API

同步API在以下场景中特别有用：

1. 命令行工具开发：需要立即执行高亮操作
2. 服务端渲染：在构建阶段同步生成高亮代码
3. 性能敏感场景：避免异步带来的微小延迟
4. 简单脚本工具：不需要复杂异步逻辑的简单应用

核心同步API详解

Shiki提供了createHighlighterCoreSync方法来实现完全同步的高亮操作。其基本使用模式如下：

import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCoreSync } from 'shiki/core'
import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'

const shiki = createHighlighterCoreSync({
  themes: [nord],
  langs: [js],
  engine: createJavaScriptRegexEngine()
})

const html = shiki.highlight('console.log(1)', { lang: 'js', theme: 'nord' })

关键参数说明

1. themes：必须预先加载的主题对象数组
2. langs：必须预先加载的语言定义对象数组
3. engine：必须提供的正则表达式引擎实例

正则表达式引擎的选择

Shiki支持两种正则表达式引擎，它们在同步使用中有重要区别：

JavaScript正则引擎

这是最简单的同步方案，引擎可以立即创建：

import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
const engine = createJavaScriptRegexEngine()

特点：

• 纯JavaScript实现
• 无需额外依赖
• 性能略低于Oniguruma

Oniguruma引擎

虽然Oniguruma引擎本身是异步的，但可以通过预加载实现同步使用：

import { createOnigurumaEngine } from 'shiki/engine/oniguruma'

// 预先异步加载
const engine = await createOnigurumaEngine(import('shiki/wasm'))

// 然后可以同步使用
const shiki = createHighlighterCoreSync({
  themes: [nord],
  langs: [js],
  engine
})

特点：

• 基于WASM的高性能实现
• 需要预先异步加载
• 语法匹配更精确

性能与资源考量

使用同步API时需要注意：

1. 内存占用：所有语言和主题都会立即加载到内存中
2. 启动时间：初始化时需要加载所有资源，可能导致启动延迟
3. 包体积：特别是使用WASM引擎时，会显著增加包大小

最佳实践建议

1. 在浏览器环境中谨慎使用同步API，可能影响页面加载性能
2. 对于服务端应用，可以考虑在启动时预先加载所有资源
3. 按需加载语言定义，避免不必要的内存消耗
4. 对于简单项目，JavaScript正则引擎通常是更好的选择

错误处理

同步API中的错误会立即抛出，需要使用try-catch进行处理：

try {
  const html = shiki.highlight(code, { lang: 'js', theme: 'nord' })
} catch (e) {
  console.error('高亮处理失败:', e)
}

常见错误包括：

• 未加载的语言或主题
• 无效的代码输入
• 引擎初始化不完整

通过合理使用Shiki的同步API，开发者可以在特定场景下获得更简单直接的高亮处理能力，同时需要注意同步操作带来的各种约束和限制。

shiki A beautiful Syntax Highlighter. 项目地址: https://gitcode.com/gh_mirrors/sh/shiki