保留格式，声明语义，必须嵌套为；prism依赖class精确匹配语言标识符；行内与块级需分离css处理；服务端渲染须避免双重转义。
pre 和 code 标签的语义分工必须分清
很多人直接把 <pre class="brush:php;toolbar:false;"><code>...</code></pre> 当作“高亮标配”，但实际中常漏掉关键点：<pre class="brush:php;toolbar:false;"></pre> 负责保留换行与空格，<code> 仅表示这段是计算机代码——两者缺一不可，且嵌套顺序不能反。如果只用 <code>，缩进和多行会塌成一行；如果只用 <pre class="brush:php;toolbar:false;"></pre>，缺乏语义，对屏幕阅读器和 SEO 不友好。
实操建议：
- 始终采用
<pre class="brush:php;toolbar:false;"><code class="js">...</code></pre>结构，class放在<code>上（不是<pre class="brush:php;toolbar:false;"></pre>），供高亮库识别语言 - 避免在
<code>内写 HTML 标签（如<div>），必须写时先做 HTML 实体转义：<code><div> - 不要给
<pre class="brush:php;toolbar:false;"></pre>设固定高度或overflow: hidden，否则可能截断内容；用max-height+overflow-y: auto更安全 - 整段代码灰底白字，无任何颜色变化 → 检查
class是否拼错或缺失 - 只有注释变绿，其余全黑 → 可能用了
language-html却放了 JS 代码，语言类型不匹配 - 引入了 Prism CSS 但没引入对应语言插件（如
prism-python.min.js）→ 需确认 JS 文件是否加载完整
使用 Prism.js 时 class 命名必须匹配语言标识符
Prism.js 默认靠 <code> 的 class 属性识别语言，比如 language-python、language-json。写成 lang-py 或漏掉 language- 前缀，高亮就会失效——连基础关键字都不上色。
常见错误现象：
最小可用示例：
function hello() {
console.log("Hi");
}
对应需加载：prism.js + prism.css + （可选）prism-javascript.min.js（若用默认构建版，JS 已含常用语言）
内联代码和块级代码不能混用同一套样式
<code> 本身既可用于行内（如 console.log()），也可嵌在 <pre class="brush:php;toolbar:false;"></pre> 中作块级展示。但 CSS 若统一设 display: block，会导致行内 <code> 换行破坏段落流；若只设 font-family: monospace，又会让块级代码失去缩进控制。
解决思路：
- 块级代码：依赖
<pre class="brush:php;toolbar:false;"><code></code> 组合，CSS 针对 <code>pre code</code> 设置 <code>display: block</code>、<code>padding</code>、<code>border-radius</code> 等</pre> - 行内代码：单独定义
code:not(pre > code)，保持display: inline，仅调字体和背景浅灰 - 别用
code { white-space: pre-wrap }全局设置，它会让行内代码也保留多余空格，排版错乱
服务端渲染或静态站点生成时要注意 HTML 转义时机
如果你用 Next.js、Hugo 或 Jekyll 输出代码块，容易在两个环节出问题：一是模板引擎提前转义了 和 <code>>，导致页面显示 <div> 而非 <div>；二是高亮库（如 Prism）在客户端执行时，发现 DOM 里已经是转义后的字符串，无法正确解析语法结构。
<p>关键判断点：</p>
<ul>
<li>查看浏览器 Elements 面板中 <code><code> 内容是否已变成 < → 是，则模板层转义过早，需用 {{ raw }}...{{ endraw }}（Hugo）或 dangerouslySetInnerHTML（React）绕过
Prism.highlightAll() 在 useEffect 或 DOMContentLoaded 后调用<pre class="brush:php;toolbar:false;"><code></code> 却漏掉 <code>class</code> → 检查其语法高亮插件配置，确保输出带 <code>language-xxx</code></pre>
最易被忽略的是：本地开发时一切正常，上线后高亮消失——大概率是 CDN 缓存了旧版 CSS/JS，或构建工具把 language- 类名当作无用 CSS 删除了。
