本文详解 highlight.js 的标准集成方式，涵盖 cdn 快速引入、html 结构规范、语言标识方法及常见错误规避，帮助开发者一步到位实现美观、可靠的代码语法高亮。
本文详解 highlight.js 的标准集成方式，涵盖 cdn 快速引入、html 结构规范、语言标识方法及常见错误规避，帮助开发者一步到位实现美观、可靠的代码语法高亮。
Highlight.js 是轻量、易用且支持超 200 种语言的前端代码高亮库。但许多初学者在集成时会遇到“样式不生效”“代码未高亮”或“HTML 被转义显示”等问题——根本原因往往在于HTML 结构不合规、缺少语言声明、CSS/JS 加载顺序错误，或服务端代码（如 PHP）被直接暴露为纯文本而非渲染后结果。
✅ 正确集成步骤（推荐 CDN 方式）
最稳定、零配置的入门方式是使用官方 CDN（无需 npm 构建）：
<!-- 在 <head> 中引入样式 --> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css"> <!-- 在 </body> 前引入脚本 --> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script> <!-- 初始化高亮（必须放在 highlight.min.js 之后） --> <script>hljs.highlightAll();</script>
?
highlightAll()会自动查找所有<pre class="brush:php;toolbar:false;"></code> 块并应用高亮，无需手动遍历 DOM —— 这比 <code>highlightBlock()</code> 更可靠，尤其适用于动态渲染内容。</p></blockquote><h3>✅ HTML 结构必须规范</h3><p>Highlight.js <strong>仅识别标准语义化结构</strong>：<code><pre class="brush:php;toolbar:false;"><code class="xxx">...</pre>。你原代码中的<div class="code">... 是无效的，会导致高亮失败：<p>❌ 错误写法（无 pre/code、无语言类）：</p><div class="aritcle_card flexRow"> <div class="artcardd flexRow"> <a class="aritcle_card_img" href="/xiazai/skill10806" title="Expanso json-flatten"><img src="https://img.php.cn/upload/skill/001/246/273/6adaf20d79f23518.jpg" alt="Expanso json-flatten" ></a> <div class="aritcle_card_info flexColumn"> <a href="/xiazai/skill10806" title="Expanso json-flatten">Expanso json-flatten</a> <p>通过 CLI 或 MCP 服务器，使用 Expanso Edge 管道扁平化嵌套 JSON 对象。</p> </div> <a href="/xiazai/skill10806" title="Expanso json-flatten" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div><pre class="brush:php;toolbar:false;"><div class="code"> echo "Hoeveel stapels wil je hebben? " . PHP_EOL; // ... 其他 PHP 代码 </div></pre><p>✅ 正确写法（带语言标识 + 保留原始换行与空格）：</p><pre class="brush:php;toolbar:false;"> echo "Hoeveel stapels wil je hebben? " . PHP_EOL; $k = readline(""); for ($i = 0; $i < $k; $i++) { for ($j = 0; $j <= $i; $j++) { echo "*"; } echo PHP_EOL; } </pre><p>⚠️ 注意事项：</p> <ul> <li>所有 <code>、<code>>、&等特殊字符必须 HTML 实体转义（如→ <code>），否则浏览器会解析为标签或报错；使用 <pre class="brush:php;toolbar:false;"></code> 保证缩进与换行保留；</li><li><code>class="php"</code>（或 <code>lang="php"</code>）<strong>必不可少</strong>——Highlight.js 依赖它自动选择对应语法解析器；</li><li>不要将 PHP 代码直接写在 HTML 中执行（除非你运行的是 PHP 服务端环境并已正确解析）；静态页面中，它只是待高亮的纯文本。</li></ul><h3>✅ 如需自定义主题或构建项目（非 CDN 场景）</h3><p>若坚持使用 npm 方式，请确保：</p><ul><li>SCSS 导入路径正确（<code>@import 'highlight.js/scss/default.scss';</code> 更推荐，避免 CSS 路径失效）；</li><li>JS 初始化时机合理（建议 DOMContentLoaded 后执行）；</li><li>显式指定语言以提升准确性（尤其对多语言混排）：<pre class="brush:php;toolbar:false;">document.querySelectorAll('pre code').forEach(block => { hljs.highlightElement(block); // 替代已废弃的 highlightBlock() });</pre>? 总结
- 首选 CDN：省去构建烦恼，版本可控，加载稳定；
- 结构即契约：
<pre class="brush:php;toolbar:false;"><code class="xxx"></code> 是唯一被识别的容器；</pre>- 转义不可少：服务端代码片段需实体编码后再嵌入 HTML；
- 语言类必填：
language-php、language-javascript等明确告知解析器目标语法；- 避免在静态 HTML 中尝试执行 PHP —— 它在此处仅作为展示文本，而非运行逻辑。
完成以上配置后，你的 PHP 代码块将立即呈现专业级语法高亮，支持关键字、字符串、注释等精准着色，大幅提升技术文档可读性。
