Highlight.js 项目构建与测试完全指南

Highlight.js 项目构建与测试完全指南

highlight.js JavaScript syntax highlighter with language auto-detection and zero dependencies. 项目地址: https://gitcode.com/gh_mirrors/hi/highlight.js

前言

Highlight.js 是一个流行的代码语法高亮库，支持超过180种编程语言。作为开发者，了解如何正确构建和测试该项目对于贡献代码或自定义使用至关重要。本文将全面介绍 Highlight.js 的构建流程和测试方法。

快速开始

对于大多数开发场景，只需关注 Node.js 环境的构建和测试：

npm run build
npm run test

如果需要测试浏览器环境，则需要额外执行：

npm run build-browser
npm run test-browser

详细构建指南

准备工作

构建 Highlight.js 需要 Node.js 环境。在开始前，请确保：

1. 已安装 Node.js（建议使用 LTS 版本）
2. 在项目目录下执行 npm install 安装所有依赖

构建工具详解

构建工具位于 tools/build.js，支持多种构建选项：

1. 基础浏览器构建（仅包含常用语言）：

   node tools/build.js :common
   

2. 完整 Node.js 构建（包含所有语言）：

   node tools/build.js -t node
   

3. 调试构建（指定语言，不压缩代码）：

   node tools/build.js -n python ruby
   

注意：在某些 Linux 发行版中，Node.js 可执行文件可能名为 nodejs 而非 node，需要相应调整命令。

构建结果将输出到 build/ 目录，包含压缩版和未压缩版文件。

测试方法论

可视化调试

开发语言定义时，推荐使用可视化工具进行初步测试：

1. 构建仅包含目标语言的调试版本：

   node tools/build.js -n 语言名称
   

2. 打开 tools/developer.html 开发者工具

3. 选择目标语言并输入测试代码片段

测试代码片段应简短但具有代表性，不需要覆盖所有语法情况。

自动化测试

Highlight.js 使用 Mocha 测试框架，测试文件位于 test/ 目录。

完整测试流程：

1. 将测试代码片段放入 test/detect/语言名称/default.txt
2. 构建完整包：

   node tools/build.js -t node
   

3. 运行测试：

   npm test
   

或使用组合命令：

npm run build_and_test

标记测试

对于复杂的语法情况，可以创建专门的标记测试：

1. 测试代码放在 test/markup/语言名称/测试名称.txt
2. 预期结果放在 test/markup/语言名称/测试名称.expect.txt

使用开发者工具生成预期结果时，务必手动选择目标语言，避免自动检测干扰。

Docker 开发环境

基础使用

1. 构建镜像：

   docker build -t highlight-js .
   

2. 运行容器（映射80端口）：

   docker run -d --name highlight-js --rm -p 80:80 highlight-js
   

3. 访问 http://127.0.0.1/tools/developer.html 进行测试

高级用法

绑定本地源代码实现实时开发：

docker run -d --name highlight-js --volume $PWD/src:/var/www/html/src --rm -p 80:80 highlight-js

修改本地文件后，触发容器内重建：

docker exec highlight-js node tools/build.js :common

最佳实践建议

1. 语言相关性调优：当自动检测出现问题时，应调整语言定义中的 relevance 值
2. 测试覆盖：新语言贡献应包含足够的标记测试用例
3. 构建选择：日常开发可使用 :common 构建加快迭代速度
4. Docker 使用：推荐在贡献代码前使用 Docker 环境进行完整测试

通过掌握这些构建和测试技术，开发者可以高效地参与 Highlight.js 项目开发或进行自定义修改。

highlight.js JavaScript syntax highlighter with language auto-detection and zero dependencies. 项目地址: https://gitcode.com/gh_mirrors/hi/highlight.js