企业官网建设流程全解析

Astro 中如何使用 @astrojs/prism 的 Prism 组件与 runHighlighterWithAstro 实现代码高亮

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro

在 Astro 项目里展示代码片段时，原生<pre><code>只能输出纯文本。@astrojs/prism这个包（仓库内路径 packages/astro-prism/README.md）基于prismjs提供两种服务端高亮方式：一个可直接在.astro文件里使用的<Prism />组件，以及一个导出函数runHighlighterWithAstro，用于在代码中自行调用高亮逻辑。本文按“安装 → 使用组件 → 使用函数 → 验证输出”的顺序，说明如何在你自己的 Astro 站点中完成代码高亮。

前置条件

根据 packages/astro-prism/package.json：

• Node.js 版本要求>=22.12.0（engines字段）。
• 运行时依赖为prismjs ^1.30.0，随包安装，无需单独引入。
• 当前包版本为4.0.2，高亮在构建/渲染时完成（服务端），不依赖浏览器端脚本。

安装：

npm install @astrojs/prism

高亮只负责给 HTML 片段加上 token 结构，token 的颜色需要 CSS 主题提供。@astrojs/prism本身不附带主题样式，需引入一个 Prism 主题样式表（如 Prism 官方主题），仓库文档没有指定使用哪一个，由你自行选择。

使用<Prism />组件

<Prism />组件在.astro文件中直接使用。README 给出的用法：

--- import { Prism } from '@astrojs/prism'; --- <Prism lang="js" code={`const foo = 'bar';`} />

组件接受三个 props（见 Prism.astro 的 Props 接口）：

• code: string—— 必填，要高亮的代码文本；
• lang?: string—— 可选，Prism 语言标识，如js；不传时按plaintext处理；
• class?: string—— 可选，附加到外层<pre>上的类名。

组件的渲染结果是<pre>套<code>结构，language-<lang>类同时写在<pre>和<code>上，高亮后的 HTML 通过set:html注入：

<pre class="<你的 class> language-js"><code class="language-js" set:html={html} /></pre>

多行代码建议用模板字符串传入，例如（以下代码块内容为示例，可自行替换）：

--- import { Prism } from '@astrojs/prism'; --- <Prism lang="astro" code={` --- const title = 'Hello'; --- <h1>{title}</h1> `} />

lang="astro"是合法取值，高亮器会为 astro 语言单独注册语法（见下文语言加载规则）。

直接调用 runHighlighterWithAstro

当不在组件上下文、需要拿到高亮后的 HTML 字符串时（例如在端点、工具函数或自定义渲染逻辑中），可以导入内部导出的runHighlighterWithAstro。函数签名见 src/highlighter.ts：

runHighlighterWithAstro(lang: string | undefined, code: string)

README 中的官方示例（astro语言，注意该示例调用未加await，实际使用时这是异步函数，应等待其返回）：

import { runHighlighterWithAstro } from '@astrojs/prism'; runHighlighterWithAstro( ` --- const helloAstro = 'Hello, Astro!'; --- <div>{helloAstro}</div> `, 'astro', );

返回值为对象{ classLanguage, html }：

• classLanguage形如language-<lang>，可直接用作 class；
• html是 Prism 高亮后的 HTML 片段，未找到对应语法时回退为原始code文本。

语言加载规则

runHighlighterWithAstro对lang的处理逻辑（来自 src/highlighter.ts），在传入语言前值得了解：

1. lang为空时按plaintext处理，classLanguage为language-plaintext；
2. lang === 'ts'时内部映射为typescript并加载；
3. lang === 'astro'时先加载typescript，再通过addAstro注册 astro 语法。addAstro（src/plugin.ts）以 markup 为基础扩展出 astro 语法；若 TypeScript 语言未加载成功，astro 的 script 部分会按 JavaScript 处理并打印警告Prism TypeScript language not loaded, Astro scripts will be treated as JavaScript.；
4. 其他语言先确保加载markup-templating（Prism 对多种语言要求它存在），再加载目标语言。

如果最终Prism.languages[lang]仍不存在，会打印警告Unable to load the language: <lang>，此时html就是未高亮的原始代码，页面不会报错。

在 Cloudflare Workers 环境下，语言加载走单独实现 src/loadLanguages-workerd.ts（通过package.json的#prism-loadLanguagesimports 条件解析），<Prism />组件在该环境下的修复见 CHANGELOG.md 4.0.2 条目。

验证结果

1. 运行npm run build（或npm run dev访问页面），确认构建过程没有出现Unable to load the language: xxx警告——出现说明该语言标识无法加载，<Prism>会退化为纯文本输出。
2. 查看页面源码，确认输出结构为<pre class="language-xxx"><code class="language-xxx">，且<code>内部包含 Prism 生成的 token 标记（<span class="token ...">）而非原始代码文本。
3. 浏览器中代码片段呈现语法着色，说明 Prism 主题 CSS 已正确生效；结构正确但无色时，检查主题样式表是否引入。

参考文件

• packages/astro-prism/README.md —— 组件与runHighlighterWithAstro的官方用法
• packages/astro-prism/Prism.astro —— 组件实现与 props 定义
• packages/astro-prism/src/highlighter.ts —— 语言加载与高亮逻辑
• packages/astro-prism/src/plugin.ts —— astro 语法注册

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro