Shiki v2.0.0

Shiki v2.0.0 本身是一个平淡无奇的版本。

如果你错过了，我们在小版本更新中逐步引入了一些非常酷的新功能：

版本	值得注意的新功能
v1.1.0	更好的 Twoslash 支持
v1.3.0	新增 `structure: inline` 选项
v1.6.0	作用域颜色替换，感谢 @QuentinRoy
v1.8.0	暴露 `.dispose()` 方法用于显式资源清理
v1.10.0	引入了 Grammar State 用于部分代码高亮
v1.15.0	引入了 JavaScript Engine，具有更好的可移植性和更小的包体积
v1.16.0	支持同步使用
v1.19.0	引入了 `enableDeprecationWarnings()` 函数以便于迁移。支持对象风格的 `htmlStyle` 和新的 `htmlAttrs` 主题化 token。
v1.23.0	新增 `@shikijs/colorized-brackets` 包，感谢 @MichaelMakesGames
v1.24.0	改进了 JavaScript 引擎的性能和准确性，感谢 @slevithan
v1.25.0	将主题和语言分离到 `@shikijs/themes` 和 `@shikijs/languages` 包中
v1.26.0	引入了预编译语言包，以减少包体积并提高性能
v1.27.0	新增 `shiki-codegen` 包，便于细粒度的包创建
v1.29.0	改进了 transformer 匹配算法，引入 `matchAlgorithm` 选项。感谢 @fuma-nama

在这些新功能中，我们还增加了许多新语言支持和新的主题。查看语言和主题列表以获取完整列表。

同时，非常感谢 @slevithan 在 oniguruma-to-es 上的出色工作，使得 JavaScript 引擎支持 97.2% 的所有语言。

破坏性变更

在 v2.0.0 中没有硬性的破坏性变更。它作为即将到来的 v3.0.0 的垫脚石。

v2 中唯一的变化是，Shiki 现在会在你使用计划在 v3 中移除的废弃 API 时发出警告。由于这可能会影响最终用户，我们进行了主版本升级，以便你可以选择启用警告并为未来的移除做好准备。

v1.x：废弃的 API 仍然支持，仅在类型级别标记。可选择启用运行时警告。
👉 v2.0：没有破坏性变更，但默认启用运行时废弃警告。
v3.0：移除废弃的 API，破坏性变更。

预计 v3.0.0 将在 v2.0.0 之后不久发布。

自动化迁移

为了帮助迁移过程，社区成员 Covolute 提供了一个自动化代码修改工具，处理了从 v1 到 v2 的大部分 API 变更。你可以直接运行：

bash

npx covolute@latest shiki/v1-to-v2

废弃内容

我们强烈建议你尽快迁移废弃内容，并以警告信息为指南。

`getHighlighter` -> `createHighlighter`

没有功能上的变化，更像是纠正命名以避免混淆。应该是一个简单的查找和替换操作。

WASM 相关 API

自从在 v1.16 引入引擎系统以来，WebAssembly 相关的依赖不再是硬性要求。为了便于 tree-shaking 并将引擎与核心解耦，两个包被提取出来：@shikijs/engine-oniguruma 和 @shikijs/engine-javascript。这些也从主包中重新导出为 shiki/engine/oniguruma 和 shiki/engine/javascript。

你可能需要更改导入路径：

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

createHighlighterCore 中的 loadWasm 字段被替换为 engine 字段：

import { createHighlighter } from 'shiki'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'
const shiki = await createHighlighter({
  // ...
  loadWasm: () => import('shiki/wasm'), 
  engine: createOnigurumaEngine(() => import('shiki/wasm')), 
})

Shiki 兼容包

为与 v0.14 兼容而构建的 @shikijs/compat 包现已废弃。请迁移到主包。该包将在 v3.0 中移除。

Transformer 匹配算法

matchAlgorithm 选项在 v1.29.0 中引入，允许用户选择匹配算法。默认值将在 v3.0.0 中从 v1 更改为 v3。我们建议显式设置 matchAlgorithm 选项以避免未来的破坏性变更。

了解更多。

其他废弃内容

createdBundledHighlighter 需要单个对象风格的参数
@shikijs/core
- 正则引擎 createJavaScriptRegexEngine 和 createOnigurumaEngine 不再包含在内，分别从 @shikijs/engine-oniguruma 和 @shikijs/engine-javascript 导入
- createHighlighterCore 现在明确要求传递 engine 字段
- createHighlighterCore 中的 loadWasm 字段被替换为 engine 字段
- @shikijs/core/wasm-inline 被替换为 @shikijs/engine-oniguruma/wasm-inline
- 从 @shikijs/vscode-textmate 导入 FontStyle 和 StackElementMetadata，而不是 @shikijs/core

调整警告

如果你更喜欢硬错误而不是警告，可以在使用 Shiki 之前运行以下代码，第一个参数决定是否启用警告，第二个参数决定是否将警告作为错误抛出：

import { enableDeprecationWarnings } from 'shiki/core'

enableDeprecationWarnings(true, true) // 启用警告并抛出错误

// 之后使用 crateHighlighter(...) 等

禁用警告

如果你想禁用警告：

import { enableDeprecationWarnings } from 'shiki/core'

enableDeprecationWarnings(false)

作为用户尝试

如果你通过其他包间接使用 Shiki，比如 vitepress 或 @nuxt/content，并且你无法直接控制 Shiki 的版本，你可以尝试在 package.json 中添加以下行来强制使用 Shiki v2.0.0。这将帮助你检查你使用的框架/工具是否依赖于废弃的 Shiki API。如果是，请向他们的仓库报告，以提高对即将到来的变更的认识。谢谢！

json

{
  "resolutions": {
    "shiki": "^2",
    "@shikijs/core": "^2",
    "@shikijs/transformers": "^2",
    "@shikijs/markdown-it": "^2",
    "@shikijs/rehype": "^2"
  }
}

反馈

欢迎任何反馈！请随时在 GitHub 上提出问题，告诉我们你的想法。

Shiki v2.0.0 ​

破坏性变更 ​

自动化迁移 ​

废弃内容 ​

getHighlighter -> createHighlighter ​

WASM 相关 API ​

Shiki 兼容包 ​

Transformer 匹配算法 ​

其他废弃内容 ​

调整警告 ​

禁用警告 ​

作为用户尝试 ​

反馈 ​