很多人在 CSDN 上看到一段排版舒服的代码块，第一反应是"这肯定是平台自己封装的富文本组件，我自己的页面做不出来"。真去翻一次开发者工具就会发现，那东西朴素得有点让人失望：无非是一层容器、一个头部工具条、一个 pre 包着 code，再加上一段控制复制按钮的 JavaScript。没有影子 DOM，没有 canvas，也没有任何黑魔法。你拿记事本写一个 html 文件，双击打开，同样能做出九成相似的效果。
这篇东西就是把我自己复刻这套代码块样式的过程完整摊开讲一遍，包括结构怎么划、CSS 参数取多少、语法高亮要不要引库、复制按钮为什么在本地会失灵，以及行号、横向滚动、深色模式这些一旦上线就会冒出来的问题。适合正在写技术博客、做文档站点、给后台系统写帮助页的人看，前端基础一般也能跟上，因为核心就是 html 加 css，JavaScript 只占很小一块。
1. 先把 CSDN 代码片拆开：它到底是几层结构叠出来的
拆解任何 UI 的第一步都不是抄样式，而是先搞清层级关系。在 CSDN 文章页里对着代码块右键"检查"，你会看到一段被折叠得很整齐的 DOM，展开之后层次其实非常浅，通常不超过三层嵌套。这个观察很重要，因为很多人复刻失败的原因不是 CSS 写错了，而是一开始就把结构搞复杂了，套了五六个 div，最后定位互相打架，圆角和阴影到处漏。
我习惯把这类组件按职责切成三段：外层是容器层，负责圆角、背景底色、外边距，是整个块的视觉边界；中间是头部层，横跨顶部一条，左边放语言名，右边放复制按钮；底部是内容层，也就是真正承载代码的那块区域，负责内边距、字体、行高和滚动。三段各管各的，互不越界，这样后面改任何一个参数都不用担心牵一发动全身。
| 层级 | 典型标签 | 主要职责 | 容易踩的坑 |
|---|---|---|---|
| 容器层 | figure或div | 圆角、底色、外层间距、整体阴影 | 用figure时忘了清掉浏览器默认的 margin |
| 头部层 | figcaption或div | 语言标签、复制按钮、顶部分隔 | 高度没固定，复制按钮换文字时整条会跳 |
| 内容层 | pre > code | 代码文本、字体、行高、横向滚动 | 忘了设overflow-x，长行把页面撑宽 |
1.1 容器层、头部层、内容层各自的边界在哪
容器层最忌讳的一点是把内边距写在它身上。我一开始就是这么干的，padding: 16px直接加在外层，结果头部工具条的背景色没办法铺满整条，左右两边各留出一条缝，看着特别别扭。正确的做法是容器只负责边框和圆角，padding设为 0，把内边距下沉到内容层，头部层则用不满宽的背景块去贴住容器的左右边缘。这样头部条的底色才能严丝合缝地贴住圆角内侧。
内容层的边界问题主要是横向溢出。代码里但凡有一行特别长，比如一个没换行的长 URL 或者一大串链式调用，如果不做处理，pre元素会按照内容宽度撑开，把整个页面顶出一个横向滚动条。解决办法是给内容层加上overflow-x: auto，让它自己内部滚，这样页面整体宽度不受影响。这一点在移动端尤其明显，我见过不少博客在手机上整页都能左右拖动，根源就是这里。
还有一个小细节值得单独说：容器层最好不要设固定高度。代码块的行数是不确定的，三行和三十行都得能正常显示。有人为了"看起来整齐"设了height: 300px，结果短代码块下面拖着一大片空白，长的又被截断。让它按内容撑开，是这类组件唯一合理的选择。
1.2 视觉参数实测：圆角、内边距、字号这些数字从哪来
复刻样式最容易走偏的地方就是凭感觉调数值。我的建议是直接在浏览器里量，别猜。用开发者工具的取色器和标尺对着目标元素点几下，很快就能把关键参数凑出来。下面这组是我自己反复调过、在 14 寸笔记本和 1080P 显示器上都看着舒服的取值，你可以当基准再微调。
- 容器圆角：
6px到8px，超过 10px 会显得过于圆润，失去技术感 - 内容层内边距：上下
12px、左右16px，这个比例在视觉上最平衡 - 代码字号：
14px，行高1.6，也就是约22.4px，行与行之间不挤不散 - 头部高度：
36px左右，语言标签字号12px - 等宽字体栈：
Consolas, Menlo, Monaco, "Courier New", monospace
行高这一项特别值得较真。因为等宽字体本身字面高度大，行高给到 1.4 以下，中文注释和英文代码混排时就会显得拥挤；给到 1.8 以上，代码块又会被拉得很松散，一屏看不了几行。1.6 是我试过之后觉得最耐看的值，长期阅读眼睛不累。字号也别贪大，14px 配上等宽字体，实际视觉宽度差不多相当于常规正文的 15.5px，已经足够清晰了。
2. 用 pre 和 code 搭骨架：语义化标签怎么分工
结构定下来之后，选标签这一步其实有两个流派：一派全部用div，想怎么摆怎么摆；另一派坚持用语义化标签，figure配figcaption加pre > code。我自己是坚定的后一派，理由不是"显得专业"，而是这套标签能免费拿到两样东西：屏幕阅读器能识别出这是代码内容并正确朗读换行，搜索引擎也能更准确地判断页面里存在代码片段。
pre和code的分工必须说清楚，这是新手最容易混的地方。code负责"这是代码"这个语义，pre负责"保留空白和换行"这个排版行为。也就是说，pre是拿来维持缩进和换行的，code是拿来标明内容的。两者嵌套使用，才是标准写法。如果你只用pre不加code，浏览器还是会按原样显示，但语义上丢了信息；只用code不加pre，代码里的缩进和换行会被浏览器合并成一整行，看着就是一坨。
2.1 语义化标签和纯 div 方案的取舍
用figure有个必须记住的副作用：浏览器默认给figure加了上下各1em的 margin，左右还有40px。如果你不复位，会发现代码块左边莫名其妙空出一大块，而且和上下段落的间距也不对。开工第一件事就是把这两个值清掉。这不是什么坑，是规范里写明的默认样式，只是很多人不看。
纯div方案的唯一优势是省心，不用记这些默认值。但代价是语义全丢，而且以后要做"点击代码块展开全文"这类扩展时，你会发现自己没有可以挂钩的语义节点。我个人的判断标准很简单：这块内容是不是"一段带标题的代码"，是就用figure，不是就用div。绝大多数场景下都该用前者。
2.2 头部工具条：绝对定位还是 flex 布局
头部工具条里有两个元素，语言标签在左，复制按钮在右。实现方式有两种，我两种都写过，最后长期用的是 flex。
第一种是绝对定位，把复制按钮position: absolute; right: 12px; top: 8px，语言标签留在正常流里。这种写法最省事，缺点是按钮脱离文档流之后，头部条的高度必须靠语言标签撑起来，一旦语言标签的文字变了或者被隐藏，整条就会塌掉。我之前做过一个可以隐藏语言标签的版本，一切换就出问题。
第二种是display: flex; justify-content: space-between; align-items: center，两个元素都在正常流里，高度自然被内容撑开，也不会互相打扰。想加第三个元素比如"折叠"按钮，直接往里面塞就行。这个方案唯一的注意点是头部条要设min-height，避免语言标签为空时整条变得过矮。我现在默认就是 flex 方案，没有任何回头的想法。
2.3 一份可以直接跑起来的静态骨架
把上面的结论拼起来，就是一个完整的静态版本。下面这份代码我建议你直接存成.html文件，双击打开看效果，改动参数也能立刻看到变化，比在项目里调试快得多。
<!DOCTYPE html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>代码块样式试验页</title> <style> :root { --code-bg: #f6f7f9; --code-bar-bg: #eceff3; --code-border: #e2e5ea; --code-text: #24292f; --code-accent: #3a7afe; --code-radius: 8px; --code-gutter: 16px; --code-font: Consolas, Menlo, Monaco, "Courier New", monospace; } .code-card { margin: 20px 0; padding: 0; border: 1px solid var(--code-border); border-radius: var(--code-radius); background: var(--code-bg); overflow: hidden; } .code-card__bar { display: flex; align-items: center; justify-content: space-between; min-height: 36px; padding: 0 12px; background: var(--code-bar-bg); border-bottom: 1px solid var(--code-border); } .code-card__lang { font-size: 12px; letter-spacing: 0.5px; color: #6b7280; text-transform: uppercase; } .code-card__copy { border: 0; background: transparent; color: var(--code-accent); font-size: 12px; cursor: pointer; padding: 4px 8px; border-radius: 4px; } .code-card__copy:hover { background: rgba(58, 122, 254, 0.1); } .code-card__pre { margin: 0; padding: 12px var(--code-gutter); overflow-x: auto; font-family: var(--code-font); font-size: 14px; line-height: 1.6; color: var(--code-text); background: var(--code-bg); } .code-card__pre code { font-family: inherit; font-size: inherit; white-space: pre; tab-size: 4; } </style> </head> <body> <figure class="code-card"> <figcaption class="code-card__bar"> <span class="code-card__lang">html</span> <button class="code-card__copy" type="button">复制</button> </figcaption> <pre class="code-card__pre"><code><div class="box"> 内容 </div></code></pre> </figure> </body> </html>这里有个埋伏点要提前说：pre里面的内容必须做 HTML 转义。上面代码里写的<和>不是装饰，是必须的。如果你直接把真实的尖括号写进pre，浏览器会把它当标签解析，整块内容就消失了。这个问题的详细处理放在后面第 5 节讲。
3. 语法高亮：手写 span 还是引现成的库
代码块光有排版还差点意思，配色分不出关键字和字符串，读起来依然费劲。语法高亮的实现路径本质上就两条：一是自己给每个词套span加上类名，二是引入 highlight.js 或 Prism 这类现成的库。这两条路没有绝对优劣，关键是看你页面里有多少代码、代码更新频率多高。
判断标准我总结成一个很粗暴的规则：如果这个页面里代码块少于 5 个，而且内容基本不动，就手写；超过 5 个或者经常更新，就引库。手写的好处是零依赖、零构建、整块 HTML 复制到哪都能用，特别适合那种一次性的讲解页面。缺点是改代码的时候要同步改 span，稍微一多就是体力活。
3.1 手写 token 的适用边界与类名约定
手写高亮其实就是给不同类型的词配不同的类名，比如关键字、字符串、注释、数字各一个颜色。类名没有强制标准，但我建议跟主流库靠拢，用hljs-keyword、hljs-string、hljs-comment这套命名，将来想换成现成的库，CSS 几乎不用重写。
<pre class="code-card__pre"><code class="language-javascript"><span class="hljs-keyword">const</span> list = [<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>]; <span class="hljs-comment">// 求和</span> <span class="hljs-keyword">const</span> total = list.<span class="hljs-title function_">reduce</span>(<span class="hljs-function">(<span class="hljs-params">a, b</span>) =></span> a + b, <span class="hljs-number">0</span>);</code></pre>写的时候有个细节很容易忘：=>里的>同样要转义成>，<也要转成<。我当初手写第一版的时候漏了这个，导致箭头函数那一行直接断掉，排查了好一会儿才反应过来是转义问题。
3.2 引入 highlight.js 时容易冲掉自己样式的三个地方
引库的流程很简单，挂上 CSS 和 JS，然后在页面加载后调用一次初始化。但真正上手之后，有三个地方会跟你的自定义样式打架。
第一个是背景色。库自带的主题文件里，hljs这个类通常会带上自己的background和padding。你辛苦调好的容器底色会被覆盖掉，视觉上看起来像是代码块里又嵌了一块不同颜色的区域。处理方式是在自己的 CSS 里显式覆盖.hljs { background: transparent; padding: 0; }。
第二个是字号和字体。有些主题文件里带font-family和font-size声明，作用是让高亮区域自己也能独立成一个代码样式，但在已经有容器的场景下，这就变成了双重控制。统一在.code-card__pre code上定死字体和字号，再用.hljs覆盖一层font: inherit，就不会出问题了。
第三个是初始化时机。如果你用DOMContentLoaded绑定初始化，但页面的代码块是通过异步请求后塞进 DOM 的，那后插入的块根本不会被高亮。这种情况要在内容插入完成之后手动调用一次高亮函数，指定只处理新加入的节点。
提示：引库之后一定要在暗色模式和窄屏下各看一遍。不少高亮主题的配色是针对浅底设计的，切到深色背景后，注释色和关键字色的对比度会掉到看不清的程度。
4. 复制按钮：从能用到好用中间隔着好几个坑
复制按钮看着简单，实际上是我在这个组件上花时间最多的地方。原因很简单，它的核心 API 有环境限制，一旦你没意识到这个限制，就会陷入"代码明明没问题为什么点了没反应"的困惑里。
4.1 为什么本地双击打开 html 时复制会失灵
现在推荐的写法是navigator.clipboard.writeText()，但它有一个硬性前提：页面必须运行在安全上下文里，也就是https协议，或者localhost。如果你只是双击本地文件、地址栏显示的是file://开头，Chrome 里这个 API 会直接不可用，navigator.clipboard甚至是undefined。
我第一次遇到这个现象的时候，一度以为是浏览器版本问题，换了两个浏览器都一样，后来才想明白是协议的问题。所以调试阶段必须准备两条路：要么起一个本地静态服务器，用localhost访问；要么老老实实写降级方案，别指望单一 API。
4.2 一套带降级的复制函数
降级方案用的是老办法：动态创建一个textarea，把文本塞进去，选中，然后调用document.execCommand('copy')。这个方法虽然被标记为过时，但在不支持 Clipboard API 的环境里依然是唯一可行的兜底。
function copyText(text) { if (navigator.clipboard && window.isSecureContext) { return navigator.clipboard.writeText(text); } return new Promise(function (resolve, reject) { var ta = document.createElement('textarea'); ta.value = text; ta.setAttribute('readonly', ''); ta.style.position = 'fixed'; ta.style.top = '-9999px'; ta.style.opacity = '0'; document.body.appendChild(ta); ta.select(); ta.setSelectionRange(0, ta.value.length); var ok = false; try { ok = document.execCommand('copy'); } catch (e) { ok = false; } document.body.removeChild(ta); ok ? resolve() : reject(new Error('复制失败')); }); }注意ta.style.position = 'fixed'和top: -9999px这两行。早期有人用display: none隐藏 textarea，结果在某些浏览器里选不中，复制出来的内容为空。用定位移出视口是更稳的做法，元素还在渲染树里，选中逻辑正常工作。
按钮的点击反馈也值得花两分钟做一下。最简单的做法是点击后把按钮文字从"复制"改成"已复制"，setTimeout两秒后改回来。但这里有个隐患：如果用户两秒内连点三次，就会挂起三个定时器，最后一个先执行完，按钮文字会提前变回去。稳妥的写法是把定时器 ID 存下来，每次点击前先clearTimeout一次。
4.3 复制出来的文本多空行、少换行是怎么回事
这个问题在我自己的页面上出现过，非常费解：明明页面上看着是五行代码，粘贴到编辑器里变成了九行，中间全是空的。后来定位到原因，是我在写 HTML 时为了让源码好看，pre内部的每行代码都做了缩进对齐，而那些缩进用的空格和换行，textContent会原封不动地取出来。
解决办法有两个。一是写pre内部内容时不要为了源码美观做额外缩进，让它左对齐到code标签的位置。二是取文本时不要用innerText，尽量用textContent，然后在取到之后自己做一次清理。innerText会受 CSS 影响，如果页面上有white-space或者隐藏元素，取出来的结果可能和你想的完全不一样，这个坑我踩过一次就不想再踩第二次。
var raw = codeEl.textContent; // 去掉首尾多余空行，保留中间正常的缩进 var clean = raw.replace(/^\s*\n+/, '').replace(/\n+\s*$/, '');5. 只有真做过才会遇到的细节：转义、行号、长行、移动端
这一节讲的全是上线之后才会冒出来的问题，也是最能把"能看"和"好用"区分开的地方。这些东西文档里基本不会写，因为每一条都是踩出来的。
5.1 HTML 转义：哪些字符必须换，哪些可以不换
必须转义的只有三个字符，但优先级不同。&排第一，必须换成&，否则浏览器会把<这种序列当成实体去解析。<必须换成<，这是最关键的一个，不换的话后面对内容会被当成标签吞掉。>严格来说可以不换，因为单独的>在 HTML 里不构成标签起始，但为了保险和可读性，我还是习惯一起换掉。
引号要不要换取决于上下文。在文本节点里，"和'都不需要转义；但如果这段代码是写在某个属性值里面，比如title="..."，那引号就必须处理。我的做法很粗暴：不管上下文，统一用脚本转一遍，多转总比漏转安全。
如果在 JavaScript 里动态生成高亮内容，最容易漏的是反引号和${}。模板字符串在 JavaScript 里是特殊语法，如果你用模板字符串去拼 HTML，里面真实的${会触发插值，直接把内容变空。这种问题很难一眼看出，因为浏览器控制台不会报错，你只会看到页面上的代码块少了一段。写这类代码时我一般直接换成普通字符串拼接，或者先把${转成\${，别图省事。
5.2 行号列的三种做法与各自的代价
行号看着是个小功能，实现方式却会直接影响后面的维护成本。我前后试过三种，各有各的问题。
| 做法 | 实现方式 | 优点 | 代价 |
|---|---|---|---|
| 独立栏 | 额外加一列div放数字 | 滚动时位置好控制 | 需要和代码行高严格对齐，换行就错位 |
| CSS 计数器 | 每行包一个span，用::before输出序号 | 纯 CSS，语义干净 | 代码长时 DOM 节点暴增 |
| 内联生成 | 生成阶段直接写进文本 | 最稳定 | 复制时必须剔除，否则用户会连行号一起粘走 |
我现在偏向第二种，但会加一个限制：只对超过 10 行的代码块启用。因为行号在短代码块上几乎没意义，反而占掉了本来就宝贵的左边距。长代码块加上行号，讨论问题时说"第 12 行"会很方便，这才是它真正的价值。
如果用了行号，复制功能就必须做对应处理。用户点复制，粘到编辑器里的内容如果带着一堆行号数字，那就废了。做法是在取文本时跳过行号节点，只取代码本体。所以如果你一开始就把行号写在了code内部当成文本，后面再想剥离就只能靠正则清洗，很容易误伤，这是我建议用::before生成序号的原因。
5.3 长行溢出与移动端的两个取舍
前面提过overflow-x: auto，这是基础。但用久了会发现一个体验问题：横向滚动条默认样式在各浏览器里长得都不一样，有些还会盖住最后一行代码。我的处理是给滚动条单独写样式，高度压到 8px 左右，颜色调浅，既不抢眼又不至于看不见。
.code-card__pre::-webkit-scrollbar { height: 8px; } .code-card__pre::-webkit-scrollbar-thumb { background: rgba(128, 128, 128, 0.35); border-radius: 4px; } .code-card__pre::-webkit-scrollbar-track { background: transparent; }移动端要单独说，因为代码块在小屏上是最容易崩的组件。两个取舍摆在面前：一是缩小字号，二是允许横向滚动。我选的是后者。字号降到 12px 以下之后，等宽字体在小屏上已经很难分辨l和1、0和O，读代码变成猜谜。宁可让用户左右滑一下，也要保住字号。真的嫌宽，可以用媒体查询把左右内边距从 16px 压到 12px，这能挤出一点空间，代价是视觉效果稍紧。
还有一个 iOS 上的小问题：横屏切竖屏之后，某些浏览器会自动放大字号。加一句-webkit-text-size-adjust: 100%就能压住。这个属性写在html或body上都可以，我一般放html。
6. 深色模式：颜色收进变量之后还剩两件麻烦事
前面第 2 节的代码里我把所有颜色都写成了 CSS 变量，这不是为了好看，是为了深色模式。变量抽出来之后，切主题只需要改一处根节点的变量集合，其余样式一个字都不用动。但变量抽好只是第一步，后面还有两件事必须处理，不处理的话主题切换就是半成品。
6.1 系统偏好与手动切换的优先级怎么排
prefers-color-scheme能读到系统的深色偏好，用它做默认值很合适。但它有个问题：用户在系统里设了深色，不代表他希望你这个网站也是深色，有时候他只是晚上开了系统深色。所以必须留一个手动切换的入口，而且手动选择要能覆盖系统偏好。
我的做法是在html上挂一个>:root { --code-bg: #f6f7f9; --code-text: #24292f; } @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --code-bg: #1f2430; --code-text: #d6deeb; } } :root[data-theme="dark"] { --code-bg: #1f2430; --code-text: #d6deeb; }
这里:root:not([data-theme="light"])这个写法是核心。它的意思是"系统是深色，并且用户没有明确选过浅色"，两个条件同时满足才应用深色变量。少了这个:not，用户手动选的浅色就会被系统偏好直接压掉，怎么点都切不回来。我第一次写的时候就漏了这个判断，调了半天才发现问题出在选择器上。
另外还有个体验细节：切换主题时不要加过渡动画。颜色过渡在文字上会显得糊，而且切得快的时候会有拖影。背景色和文字色直接瞬间切换，反而更干脆。
6.2 高亮主题必须跟着页面主题一起换
如果引了 highlight.js，那么主题文件是独立的一份 CSS，它有自己的颜色定义。页面切到深色之后，如果只改了自己的变量而没有换高亮主题，就会出现深色底上配深色关键字的尴尬局面，看起来像是代码被吞了。
处理方式有两种。简单的是准备两套高亮 CSS 文件，切换时通过disabled属性启用对应那一套；稍微讲究一点的是不用现成主题文件，自己按 token 类名写一套颜色规则，用 CSS 变量控制。我后来长期用的是第二种，因为自己写一遍之后，代码块的配色风格能跟整个页面统一，不会出现"这一块明显是别的地方搬来的"那种割裂感。
.code-card__pre .hljs-keyword { color: var(--hljs-keyword, #c678dd); } .code-card__pre .hljs-string { color: var(--hljs-string, #98c379); } .code-card__pre .hljs-comment { color: var(--hljs-comment, #7f848e); } .code-card__pre .hljs-number { color: var(--hljs-number, #d19a66); }深色下的 token 配色有个通用原则：饱和度要降低，亮度要拉高。直接拿浅色主题的颜色往深底上放，紫色和蓝色会显得特别刺眼，读两行眼睛就累。我一般会把关键字色的亮度提高 10% 左右，字符串色稍微压一点饱和度，整体观感会舒服很多。
我自己做这套东西最大的体会是，代码块这个组件真正的难点从来不在"怎么让它显示出来"，而在那些显示出来之后才会被发现的小问题。我前前后后改过好几版，每一版都是上线之后被人指出来的：有人复制粘贴发现多了空行，有人在手机上横滑发现滚动条盖住代码，有人晚上看觉得关键字太亮。这些问题在静态截图里一个都看不出来。所以如果你准备抄这套结构，我的建议是先把它跑起来，然后自己在手机、暗色模式、超长代码这三个场景里各点一遍，改完这几个地方，剩下的就都是锦上添花了。
