企业官网建设流程全解析

• 后端
• 企业应用

本指南围绕 iTop 仓库中随附的 highlight.js CDN 构建资源包（位于 js/highlight 目录）展开，说明这套预编译资源在 iTop 中的真实用途——为 CKEditor 富文本编辑产生的代码片段提供语法高亮——并完整讲解其目录结构、版本、按需加载语言模块、主题定制与子资源完整性（SRI）校验等实操要点。读完本文，你将能够在自己的 Web 页面中正确引入并定制这一套代码高亮能力。

一、这是什么：highlight.js 的 CDN 构建资源包

js/highlight/README.md 开门见山地说明：这个目录只包含 highlight.js 的 CDN 构建产物（pre-built distributable），即面向浏览器端直接分发使用的预编译资源，而不是用于服务端渲染的完整源码包。

Highlight.js 本身是一个用 JavaScript 编写的语法高亮器，具有四个核心特性：

• 既能在浏览器端运行，也能在服务端（Node.js 等）运行；
• 几乎可以配合任意标记语言（HTML 片段）使用；
• 不依赖任何框架（无需 jQuery、React 等）；
• 内置自动语言检测能力。

在 iTop 项目中，这一资源包被用作客户端代码片段高亮：从 datamodels/2.x/itop-portal-base/portal/templates/layout.html.twig 可以看到，模板在加载完 CKEditor 的 WYSIWYG 资源之后，紧接着引入js/highlight/highlight.min.js，注释明确写着 "Highlighter for code snippets created with CKEditor"——即专门服务于用户在富文本编辑器中粘贴/编写的代码块。

二、资源包目录结构解析

先看仓库根目录下的整体文件布局（版本与包信息来自 js/highlight/package.json）：

从 package.json 可以确认，仓库随附的资源包版本为11.9.0，包名是@highlightjs/cdn-assets，关键字为 "highlight" 与 "syntax"，README 中亦提示：如果你只想在一个.js文件中获得内置了常见语言的单一文件，直接使用highlight.min.js即可——这正是 iTop 采用的方案。

语言模块方面，iTop 仓库内置了以下可独立加载的语法文件（与es/languages/下的 ES Module 版本一一对应）：

apache、bash、cpp、csharp、css、http、javascript、plaintext、scss、sql、typescript

也就是说，即使你只用highlight.min.js之外的自定义组合，也可以按需引入上述任一语言的语法文件。

三、在页面中接入：iTop 的实际用法

iTop 门户在 layout.html.twig 中通过 Twig 模板拼接资源路径并附加版本号：

{# - Highlighter for code snippets created with CKEditor #} <script type="text/javascript" src="{{ app['combodo.absolute_url'] ~ 'js/highlight/highlight.min.js'|add_itop_version }}"></script>

这里的add_itop_version过滤器用于给静态资源追加版本参数以利于缓存刷新，app['combodo.absolute_url']则输出应用根地址。如果你要在自己的页面中做同样的接入，等价于：

<script src="js/highlight/highlight.min.js"></script>

随后在页面脚本中调用自动高亮入口即可。从 js/highlight/es/core.js 的源码可以看到核心 API 的演变：

• highlightAll()：扫描页面中所有pre code并执行高亮（当前推荐用法）；
• highlightElement(element)：对指定元素执行高亮；
• initHighlighting()/initHighlightingOnLoad()：v10.6.0 起已废弃，内部直接转为调用highlightAll()，源码中保留了deprecated(...)告警（见 es/core.js）。

因此，一个典型的最小接入片段是：

<script src="js/highlight/highlight.min.js"></script> <script> hljs.highlightAll(); </script>

如果只想高亮页面中的部分代码块，则使用：

document.querySelectorAll('pre code').forEach(function (block) { hljs.highlightElement(block); });

四、自动语言检测与按需加载语言模块

highlight.min.js内置了"常见语言"集合，因此在大多数情况下无需手工声明语言。高亮器会通过class="language-xxx"或自动检测来识别代码语言。

当你希望进一步裁剪体积、只加载若干语言时，可以改为先加载不带语言的核心构建，再按需引入语言模块。iTop 仓库在 js/highlight/languages/ 与 js/highlight/es/languages/ 中提供了成对的普通与 ES Module 版本，例如：

<!-- 使用 ES Module 按需组合 --> <script type="module"> import hljs from 'js/highlight/es/core.js'; import javascript from 'js/highlight/es/languages/javascript.js'; import sql from 'js/highlight/es/languages/sql.js'; hljs.registerLanguage('javascript', javascript); hljs.registerLanguage('sql', sql); hljs.highlightAll(); </script>

从 package.json 中的sideEffects字段可以看到，官方将es/common.js、lib/common.js与所有*.css、*.scss标记为具有副作用，这意味着使用 webpack/rollup 等打包器时，引入主题样式与公共语言包不会被当作纯模块摇树优化而误删。

五、主题样式：iTop 对 highlight.js 的 SCSS 定制

高亮效果除了 JS 逻辑，还需要配套样式表。iTop 没有直接使用styles/下的预编译 CSS，而是在自己的 SCSS 体系中重新实现了主题，这正是可以在 iTop 中深度定制的部分。

公共层变量定义在 css/common/vendors/_highlightjs.scss：

$common-vendors-highlightjs--padding: 0.9rem !default; $common-vendors-highlightjs--background-color: #282b2e !default; $common-vendors-highlightjs--color: #e0e2e4 !default; $common-vendors-highlightjs--keyword--color: #93c763 !default; $common-vendors-highlightjs--number--color: #ffcd22 !default; $common-vendors-highlightjs--string--color: #ec7600 !default; $common-vendors-highlightjs--comment--color: #818e96 !default; /* ... */

后管端（backoffice）在 css/backoffice/vendors/_highlightjs.scss 中把这些公共变量以$ibo-vendors-highlightjs--*前缀继承下来，并书写了实际的.hljs样式规则：代码块采用 Obsidian 风格配色（深色背景#282b2e、圆角、内阴影），关键字、数字、字符串、注释等 token 分别着色，且对.hljs-keyword、.hljs-selector-tag等加粗显示。

需要提醒的是：所有规则都带有!important，从源码注释看这是为了覆盖第三方styles/目录中预编译 CSS 的既有规则，确保 iTop 主题在任意引入顺序下都能生效。若你希望调整配色，只需覆盖css/common/vendors/_highlightjs.scss中对应的$common-vendors-highlightjs--*变量（所有变量均以!default声明，可被上层主题覆盖），而无需改动预编译的.css文件。

该模块由 css/backoffice/vendors/_all.scss 中的@import "highlightjs";统一引入，随其他第三方样式一起编译进最终主题。

六、CDN 加载与子资源完整性（SRI）校验

对于不走 iTop 内置路径、希望直接通过公共 CDN 分发的场景，README.md 说明了官方提供的 CDN 访问方式：资源发布在highlightjs/cdn-release仓库的build/目录下（版本号目录化）。由于仓库内文件与线上 CDN 版本一一对应（同为 11.9.0），你完全可以把highlight.min.js替换为对应的 CDN 地址以获得就近加速。

务必配合 SRI 使用：文档强调，从 CDN 加载资源时应启用子资源完整性（Subresource Integrity）校验，以确认下载到的文件未被篡改。js/highlight/DIGESTS.md 给出了每一个文件的sha384校验和，例如：

<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js" integrity="sha384-9mu2JKpUImscOMmwjm1y6MA2YsW3amSoFNYwKeUHxaXYKQ1naywWmamEGMdviEen"></script>

integrity属性由浏览器负责校验：文件内容与摘要不符时，脚本会被拒绝执行。DIGESTS.md中同时列出了highlight.js、highlight.min.js、es/highlight.js以及所有languages/*.js与es/languages/*.js的摘要，即使只加载单个语言模块，也可以为其单独附加对应的integrity值。

七、许可证

Highlight.js 采用BSD 3-Clause许可证发布，全文见 js/highlight/LICENSE。要点包括：

• 允许再分发与修改（源码或二进制形式均可），前提是保留版权声明与本许可条件；
• 未经书面许可，不得使用版权所有者或贡献者姓名进行产品背书与推广；
• 软件按 "AS IS" 提供，不附带任何明示或默示担保。

八、快速参考：相关文件索引

综上，iTop 仓库随附的 highlight.js 资源包既是一份可直接分发使用的预编译产物（版本 11.9.0、内置常见语言、提供语言模块与主题样式），又通过 Twig 模板与 SCSS 变量深度融入了门户与后管端主题。无论是直接使用highlight.min.js + highlightAll()，还是按需组合 ES Module 语言模块，抑或通过 SRI 从 CDN 加固加载链路，本文给出的路径均可直接落地实践。

• 后端
• 企业应用