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

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

highlight.js 项目地址: https://gitcode.com/gh_mirrors/hig/highlight.js

前言

Highlight.js 是一个流行的代码语法高亮库，支持超过180种编程语言。本文将详细介绍如何构建和测试 Highlight.js 项目，帮助开发者快速上手项目开发和贡献。

快速开始

对于大多数开发者来说，进行 Node.js 环境的构建和测试就足够了：

npm run build
npm run test

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

npm run build-browser
npm run test-browser

详细构建指南

环境准备

构建工具基于 Node.js 开发，构建前需要：

1. 安装 Node.js 运行环境
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 your_language
   

2. 使用开发者工具 tools/developer.html 查看代码高亮效果

测试代码片段应简短，能展示语言的主要语法特征，但不需要包含所有可能的语法结构。

自动化测试

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

完整测试流程：

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

   node tools/build.js -t node
   

3. 运行测试：

   npm test
   

或者使用组合命令：

npm run build_and_test

标记测试

对于复杂语法结构（如多种字符串字面量、正则表达式识别等），可添加专门的标记测试：

1. 测试代码：test/markup/<language>/<test_name>.txt
2. 预期结果：test/markup/<language>/<test_name>.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
   

4. 停止容器：

   docker stop highlight-js
   

高级用法

1. 绑定源代码目录：

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

2. 动态重建：

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

常见问题

1. Ubuntu/Debian 系统：可能需要创建 nodejs 到 node 的符号链接
2. 语言检测问题：可通过调整 relevance 参数优化检测效果
3. 测试失败：确保测试代码片段具有代表性且不过于复杂

结语

本文详细介绍了 Highlight.js 项目的构建和测试流程，从基础命令到高级 Docker 用法，帮助开发者快速建立开发环境并进行有效测试。掌握这些技能后，开发者可以更高效地贡献代码或开发自定义语言支持。

highlight.js 项目地址: https://gitcode.com/gh_mirrors/hig/highlight.js