快速入门

以 Markdown 格式查看在 GitHub 上编辑文档位置 22946a5

安装

命令行

composer require shikiphp/shikiphp

shikiphp 需要 PHP 8.2 或更高版本，以及 ext-json 和 ext-mbstring——几乎每个 PHP 构建都已启用这两项。无需其他依赖：不需要 Node、原生 Oniguruma 绑定或额外扩展。

第一个代码块

静态 Shikiphp 外观接口是最快的入门方式。传入代码、语言 id 和主题 id：

PHP

use Shikiphp\Shikiphp;

$html = Shikiphp::codeToHtml(<<<'PHP'
<?php
function greet(string $name): string {
    return "Hello, {$name}!";
}
PHP, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

echo $html;

codeToHtml 会返回完整且自带样式的 <pre class="shiki …"> 块。前景色和背景色以内联方式写在 <pre> 上，因此无需额外样式表也能正确渲染。

双主题（亮色和暗色）

不传单个 theme，而是传入一个 themes 映射。shikiphp 会输出 CSS 变量（例如 Shiki），让同一个渲染块能适配亮色和暗色模式：

PHP

use Shikiphp\Shikiphp;

$code = 'const answer: number = 42';

echo Shikiphp::codeToHtml($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

默认情况下，light 主题的颜色以内联方式作为默认值，而 dark 通过 --shiki-dark 变量公开。添加少量 CSS 即可启用暗色主题——同一段代码示例在 Shiki 文档中使用：

CSS

html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* and font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}

你可以通过 defaultColor 选项选择以内联方式设为默认值的主题，也可以将 defaultColor: false 设为只输出变量。

语言 id 和别名

语言通过 Shiki id 或别名引用，例如 php、ts、js、rust、python、html 等。有关如何列出所有随附语言，请参见语言；主题 id 请参见主题。

重用高亮器

外观接口会按需创建并缓存捆绑的 Highlighter，因此多次调用 Shikiphp::codeToHtml 会重用同一组语法和主题缓存。如果需要功能更丰富的 API（HAST 输出、自定义语法、令牌网格），可以直接获取该实例：

PHP

use Shikiphp\Shikiphp;

$code = 'fn main() {}';

$highlighter = Shikiphp::highlighter();
$hast = $highlighter->codeToHast($code, ['lang' => 'rust', 'theme' => 'nord']);

完整接口说明请参见 API。