企业官网建设流程全解析

• 前端

Highlight.js 是一个用 JavaScript 编写的语法高亮库，可同时运行在浏览器与服务端，不依赖任何第三方框架，并内置语言自动检测能力。本文以本仓库 README.md 为骨架，结合 src/highlight.js 源码、docs/api.rst 与构建工具，完整讲解其基础用法、自定义控制、模块导入、CDN/NPM 获取方式以及从源码构建的流程，读完后你可以直接在网页或 Node.js 项目中落地语法高亮，并按需裁剪语言包以控制体积。

Highlight.js 是什么

Highlight.js 是一个"开箱即用"的语法高亮器：它既能处理浏览器中的<pre><code>代码块，也能作为 CommonJS/ESM 模块运行在 Node.js 服务端；可以与几乎任何标记语言搭配，不依赖其他框架，并具备自动语言检测（auto-detection）能力。本仓库对应版本为11.12.0（见 package.json），以 BSD-3-Clause 协议发布。

从源码结构看，整个库由一个核心引擎（src/highlight.js）加约 180+ 个语言定义（src/languages/）以及上百个配色主题（src/styles/）组成。核心引擎通过HLJS()工厂函数构建，最终导出一个hljs单例，并暴露highlight、highlightAuto、highlightElement、highlightAll、configure、registerLanguage等完整 API（见 src/highlight.js）。

浏览器中的基本用法

在网页中使用 Highlight.js 的最小配置是：引入一个主题 CSS、引入库脚本，然后调用highlightAll()：

<link rel="stylesheet" href="/path/to/styles/default.min.css"> <script src="/path/to/highlight.min.js"></script> <script>hljs.highlightAll();</script>

highlightAll()会自动查找页面中所有<pre><code>标签并高亮，默认尝试自动检测语言。如果自动检测效果不理想，或你希望显式指定语言，可以在class属性中声明：

<pre><code class="language-html">...</code></pre>

纯文本代码块（plaintext）

希望套用 Highlight.js 的样式但不做任何高亮时，使用plaintext语言：

<pre><code class="language-plaintext">...</code></pre>

跳过某个代码块（nohighlight）

需要完全跳过某个代码块的高亮时，使用nohighlight类：

<pre><code class="nohighlight">...</code></pre>

背后的实现机制

这些约定并非魔法，而是硬编码在核心引擎的默认配置中。在 src/highlight.js 里可以看到默认选项：

• noHighlightRe: /^(no-?highlight)$/i—— 匹配到的类名对应代码块将被跳过；
• languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i—— 用于从class="language-xxx"或class="lang-xxx"中解析语言名；
• cssSelector: 'pre code'——highlightAll()默认作用的元素选择器。

highlightElement()在解析语言时还会同时读取元素自身与父级节点的 class（见 blockLanguage），因此language-*声明拥有最高优先级。若声明的语言未注册，会回退为no-highlight并在控制台输出警告。

Node.js 服务端用法

在 Node.js 中，自动检测并高亮一段代码的最小示例：

// 加载库与全部语言 hljs = require('highlight.js'); html = hljs.highlightAuto('<h1>Hello World!</h1>').value

只加载一组"常用语言"子集（与默认 Web 构建同款集合，体积更小）：

hljs = require('highlight.js/lib/common');

使用指定语言精确高亮（推荐，避免误检）：

html = hljs.highlight('<h1>Hello World!</h1>', {language: 'xml'}).value

返回对象的结构

highlight()返回的对象包含（见 src/highlight.js 与 docs/api.rst）：

highlightAuto()额外返回secondBest属性——即相关度评分第二的语言结果（可能不存在）。自动检测的逻辑在 highlightAuto 中：它对候选语言逐一执行_highlight并按relevance降序排序，纯文本始终作为兜底选项；同分时优先"基类语言"（如 C++ 优先于 Arduino），平局则保持注册顺序靠前的语言胜出。

自定义控制：highlightElement 与 configure

当初始化时机和范围需要更多控制时，可以使用highlightElement与configure两个函数，它们让你精确决定"高亮什么、何时高亮"。例如，手动实现一遍highlightAll()的等效逻辑：

document.addEventListener('DOMContentLoaded', (event) => { document.querySelectorAll('pre code').forEach((el) => { hljs.highlightElement(el); }); });

highlightElement()适合在页面加载后动态渲染的内容、或第三方框架的初始化代码中调用（见 docs/api.rst）。它默认走语言自动检测，同样支持通过 DOM 节点的class指定语言。

configure 可配置项

configure(options)用于更新全局配置，未传入的选项保持不变（见 docs/api.rst）。核心选项如下：

示例：改用自定义类名风格、并去掉类前缀：

hljs.configure({ noHighlightRe: /^do-not-highlightme$/i, languageDetectRe: /\bgrammar-([\w-]+)\b/i, // 例如 grammar-swift 风格 classPrefix: '' // 不追加类前缀 // … 其余选项保持不变 });

未转义 HTML 的安全检查

highlightElement()在渲染前会检查代码块是否包含子元素（即未转义的 HTML）。默认情况下这只会打印警告（见 src/highlight.js）；如果throwUnescapedHTML为true，则直接抛出HTMLInjectionError。这是防止 XSS 注入的重要防线，生产环境建议保证代码块内容为纯文本转义后的形式。

自定义 HTML 结构与换行保留

官方强烈推荐使用<pre><code>包裹代码块——语义清晰且"零配置即用"。如果坚持使用其他 HTML 元素（如div），需要特别留意换行的保留。

假设你的代码块标记是：

<div class='code'>...</div>

手动高亮这些块：

// 先找到所有 div.code 块 document.querySelectorAll('div.code').forEach(el => { // 再逐个高亮 hljs.highlightElement(el); });

由于div默认不会保留换行，需要额外的 CSS 帮助：

div.code { white-space: pre; }

相比之下，pre天然保留换行，这也是推荐使用它的原因。你同样可以通过插件在前后处理换行，但官方建议优先使用 CSS 方案。

与 Vue.js 集成

Highlight.js 官方提供了highlightjs/vue-plugin插件，配合 Vue 使用非常简洁。示例：

<div id="app"> <!-- 绑定 data 属性 code，自动检测语言 --> <highlightjs autodetect :code="code" /> <!-- 也可以直接传字面量与指定语言 --> <highlightjs language='javascript' code="var x = 5;" /> </div>

该插件内部仍基于highlightElement/highlightAuto的核心 API，适合在 Vue 组件化场景中按数据驱动的方式渲染高亮结果。

在 Web Worker 中运行

处理超大代码块时，可以把高亮任务放进 Web Worker，避免阻塞浏览器主线程。

主脚本中：

addEventListener('load', () => { const code = document.querySelector('#code'); const worker = new Worker('worker.js'); worker.onmessage = (event) => { code.innerHTML = event.data; } worker.postMessage(code.textContent); });

worker.js 中：

onmessage = (event) => { importScripts('<path>/highlight.min.js'); const result = self.hljs.highlightAuto(event.data); postMessage(result.value); };

注意 Worker 中通过importScripts加载的是预构建的浏览器脚本（highlight.min.js），而不是 ES 模块源码。

导入方式详解（Importing the Library）

使用前先通过npm或yarn安装（见下文"获取与安装"）。

Node.js CommonJS /require

顶层require会注册全部语言：

// 加载 highlight.js 库及全部语言 const hljs = require('./highlight.js'); const highlightedCode = hljs.highlightAuto('<span>Hello World!</span>').value

为了更小体积，加载"常用语言"子集（与默认 Web 构建同一套）：

const hljs = require('highlight.js/lib/common');

为了最小体积，只加载核心并按需注册语言：

const hljs = require('highlight.js/lib/core'); hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')); const highlightedCode = hljs.highlight('<span>Hello World!</span>', {language: 'xml'}).value

Node.js ES6 Modules /import

默认导入注册全部语言：

import hljs from 'highlight.js';

更高效的做法是只导入核心、按需注册：

import hljs from 'highlight.js/lib/core'; import javascript from 'highlight.js/lib/languages/javascript'; hljs.registerLanguage('javascript', javascript);

如果构建工具支持 CSS 导入，还可以把主题作为模块直接引入：

import hljs from 'highlight.js'; import 'highlight.js/styles/github.css';

浏览器 ES6 Modules

浏览器中请使用@highlightjs/cdn-assets包（内含预构建的 ES6 模块）。按需注册语言：

import hljs from './assets/js/@highlightjs/cdn-assets/es/core.js'; import javascript from './assets/js/@highlightjs/cdn-assets/es/languages/javascript.min.js'; hljs.registerLanguage('javascript', javascript);

注册全部语言：

import hljs from './assets/js/@highlightjs/cdn-assets/es/highlight.js';

注：以上路径是示例，实际路径取决于你将包安装/复制到项目中的位置。

也可以使用 HTMLimportmap，用命名键的方式导入：

<script type="importmap"> { "imports": { "@highlightjs": "./assets/js/@highlightjs/cdn-assets/es/" } } </script>

之后即可按命名导入：

import hljs from '@highlightjs/core.js'; import javascript from '@highlightjs/languages/javascript.min.js'; hljs.registerLanguage('javascript', javascript);

全量注册的源码机制

require('highlight.js')之所以自动注册全部语言，是因为 src/stub.js 在导入核心后遍历builtInLanguages（由 Rollup 插件注入），把每个语言模块转换为短横线命名（如grmr_1c→1c）后逐一调用registerLanguage。而 src/core.d.ts 则是核心类型声明，lib/core与lib/common等入口由构建脚本生成（见 tools/build_node.js）。registerLanguage内部还会处理语言别名注册、以及语言定义出错时的降级（出错语言会退化为纯文本占位，不拖垮整个高亮器，见 src/highlight.js）。

获取与安装（Getting the Library）

Highlight.js 可以以托管或自定义构建的浏览器脚本、或服务端模块的形式获取。开箱即用的浏览器脚本同时支持 AMD 与 CommonJS，因此可以直接配合 RequireJS 或 Browserify 使用，无需从源码构建。

不要直接链接 GitHub 上的源码：库不能脱离构建直接运行，请使用下文任一打包好的渠道。若都不满足需求，再参考构建文档 docs/building-testing.rst 自行构建。

关于 Almond：需要借助优化器为模块命名，例如：

r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js

通过 CDN 获取

多个主流 CDN 托管了预构建的 Highlight.js（内置大量常用语言）。通过 CDN 使用时还可以借助 Subresource Integrity（SRI）增强安全性，摘要文件见DIGESTS.md（由tools/templates/DIGESTS.md模板生成）。

cdnjs

Common JS：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/styles/default.min.css"> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/highlight.min.js"></script> <!-- 也可以很方便地单独加载额外语言 --> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/languages/go.min.js"></script>

ES6 Modules：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/styles/dark.min.css"> <script type="module"> import hljs from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/es/highlight.min.js'; // 也可以很方便地单独加载额外语言 import go from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/es/languages/go.min.js'; hljs.registerLanguage('go', go); </script>

jsDelivr

Common JS：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/styles/default.min.css"> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/highlight.min.js"></script> <!-- 也可以很方便地单独加载额外语言 --> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/languages/go.min.js"></script>

ES6 Modules：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/styles/default.min.css"> <script type="module"> import hljs from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/es/highlight.min.js'; // 也可以很方便地单独加载额外语言 import go from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.12.0/build/es/languages/go.min.js'; hljs.registerLanguage('go', go); </script>

unpkg

Common JS：

<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.12.0/styles/default.min.css"> <script src="https://unpkg.com/@highlightjs/cdn-assets@11.12.0/highlight.min.js"></script> <!-- 也可以很方便地单独加载额外语言 --> <script src="https://unpkg.com/@highlightjs/cdn-assets@11.12.0/languages/go.min.js"></script>

ES6 Modules：

<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.12.0/styles/default.min.css"> <script type="module"> import hljs from 'https://unpkg.com/@highlightjs/cdn-assets@11.12.0/es/highlight.min.js'; // 也可以很方便地单独加载并注册额外语言 import go from 'https://unpkg.com/@highlightjs/cdn-assets@11.12.0/es/languages/go.min.js'; hljs.registerLanguage('go', go); </script>

注意：CDN 托管的highlight.min.js并未打包所有语言（那会非常庞大）。默认打包的"常用（common）"语言清单可在官方下载页面查看，本仓库中 SUPPORTED_LANGUAGES.md 也注明了这一点：默认 Web 构建仅包含约 40 种热门语言。

下载预构建的 CDN 资源

也可以把 CDN 上托管的同一批构建产物下载下来自托管。这些构建发布在独立的 cdn-release 仓库中；如果只需要highlight.min.js加一个 CSS 文件，可以方便地用curl等工具从 CDN 端点拉取。此外还有@highlightjs/cdn-assets这个 npm 包，如果你的构建流程更习惯用npm/yarn拉取资源，可以直接依赖它。

从官网下载页获取

官网下载页可以快速生成只包含所需语言的单文件压缩包。注意：从源码构建通常能比网页下载得到更小的体积。

通过 NPM 包安装

包含全部支持语言的 NPM 包可用 NPM 或 Yarn 安装：

npm install highlight.js # 或 yarn add highlight.js

另一个包@highlightjs/cdn-assets包含预构建的 CDN 资源，包括可在浏览器中直接 import 的 ES6 Modules：

npm install @highlightjs/cdn-assets # 或 yarn add @highlightjs/cdn-assets

当然，也可以选择从源码自行构建 NPM 包。

从源码构建

当前源码始终可在 GitHub 上获取。构建命令如下：

node tools/build.js -t node node tools/build.js -t browser :common node tools/build.js -t cdn :common

从 tools/build.js 的说明可知构建目标的分工：

-t browser :common中的:common是分组标识。构建工具会按语言文件中的Category元数据过滤出common组的语言，并自动解析依赖与排序（见 tools/lib/dependencies.js），保证按序注册即可正常工作。因此你也可以写成node tools/build.js -t browser :common elixir ruby这样的"分组 + 单语言"混合参数，精细控制打包范围。

支持的语言

Highlight.js 核心库支持180+ 种语言，此外还有大量第三方语言定义可以扩展。完整语言清单（含对应 class 名与别名）见 SUPPORTED_LANGUAGES.md。该文件还说明：实际可用的语言取决于你如何构建或引入库——例如默认的 Web 压缩构建只包含约 40 种热门语言，需要额外语言时按上文"导入方式"或"获取与安装"中的示例单独加载。

语言别名的支持同样映射到核心实现：getLanguage会先按小写名称、再按别名表查找（见 src/highlight.js），registerAliases负责把别名写入别名表。社区语言包按highlightjs-<lang>命名约定发布，并可通过registerLanguage注册到自定义构建中。

环境要求（Requirements）

• 运行环境：Highlight.js 支持所有现代浏览器以及当前受支持的 Node.js 版本。就本仓库而言，package.json 中engines声明为node >= 20.0.0。
• 参与核心库开发：README 中给出的贡献者基础环境为 Node.js >= 12.x 与 npm >= 6.x，实际请以本机安装的当前版本为准（开发相关说明见 docs/building-testing.rst）。

仓库还提供debugMode()/safeMode()两个运行模式（见 src/highlight.js）。Safe Mode 是默认的生产模式：单个语言出错时其余语言照常高亮，出错语言退化为纯文本；Debug Mode 会让一切高亮中断并抛出 JavaScript 错误，仅建议在语言/库本身的测试与开发阶段使用。demo 页面即采用了hljs.debugMode(); hljs.highlightAll();的启动方式（见 demo/demo.js）。

许可证与延伸阅读

Highlight.js 以 BSD 协议发布，详见 LICENSE。

继续深入可参考以下仓库内文档：

• docs/api.rst：highlight、highlightAuto、highlightElement、highlightAll、configure、registerLanguage、addPlugin/removePlugin等 API 的完整参考；
• docs/building-testing.rst：构建与测试指南；
• docs/css-classes-reference.rst：所有语言名与 CSS scope 的引用；
• docs/plugin-api.rst 与 docs/plugin-recipes.rst：插件 API 与实用配方（如行号等能力）；
• VERSION_11_UPGRADE.md：v11 破坏性变更汇总与迁移行动项；
• SECURITY.md：长期支持（LTS）与安全相关信息。

• 前端