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	支持 Synchronous Usage
v1.19.0	引入了 `enableDeprecationWarnings()` 函数以便于迁移。支持对象样式 `htmlStyle` 和新的 `htmlAttrs` 主题令牌。
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	改进了转换器匹配算法，推出了 `matchAlgorithm` 选项。感谢 @fuma-nama

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

同时，特别感谢 @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 相关的依赖不再是硬性要求。为了促进树摇和将引擎与核心解耦，提取了两个包：@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 中被移除。

转换器匹配算法

在 v1.29.0 中引入了转换器的 matchAlgorithm 选项，允许用户选择匹配算法。默认值将在 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) // 启用警告并抛出错误

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

禁用警告

如果您想禁用警告：

import { enableDeprecationWarnings } from 'shiki/core'

enableDeprecationWarnings(false)

作为用户尝试

如果您通过其他包间接使用 Shiki，例如 vitepress 或 @nuxt/content，您可以尝试在您的 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 兼容性 ​

转换器匹配算法 ​

其他弃用说明 ​

调整警告 ​

禁用警告 ​

作为用户尝试 ​

反馈 ​