必须用仅当内容是程序真实回显的原始输出,且上下文明确指向“输出”;否则语义错误、可访问性受损,须配合与css确保格式和等宽渲染。

标签不是“显示程序输出”的快捷样式开关,它只在满足三个硬性条件时才合法:内容是程序运行后直接生成的、用户真实看到的原始文本,且上下文明确指向“输出”。用错等于在 HTML 里写错标点——语义崩了,可访问性就掉了。
什么时候必须用 而不是 或 <pre class="brush:php;toolbar:false;">
判断依据不是“长得像终端”,而是“谁生成的、在哪出现的、怎么被理解的”:
- 终端里敲
git commit -m "init" 后回显的 <samp>[main (root-commit) abc1234] init</samp> ✅ —— 真实回显、无修饰、上下文即输出 -
fetch("/api/users")返回的{"id":1,"name":"Alice"}❌ —— 这是 API 响应体,得用<code class="json"></code>
- 教程中模拟的 “运行成功,耗时 127ms” ❌ —— 非真实输出,是人工编写的说明性文字,该用普通
span或 强调 - 控制台里
console.log("done")打印出的 done ✅ —— 前提是上下文写明“浏览器开发者工具 Console 标签页中实际显示如下:”,否则语义断裂
必须配合 CSS 才能可靠呈现
浏览器对 的默认样式极简:仅可能设 font-family: monospace,但不保证换行、不保留空格、无背景、无内边距。不加 CSS 就上线,多行输出会挤成一行,空格缩进全丢。
- 至少要加:{ font-family: ui-monospace, 'SFMono-Regular', monospace; white-space: pre-wrap; }
- 若内容含 Tab 或混合空格缩进,
white-space: pre更稳妥(但会禁用自动换行) - 别依赖 自带等宽——有些旧版 Safari 或定制 UA 可能忽略,显式声明更保险
- 避免用
font-family: "Courier New"这类 Windows 专属字体,优先用系统级等宽栈
多行输出不能裸用 ,必须套
是内联元素,无法承载换行符的语义渲染。直接写:
<samp>Error: ENOENT: no such file or directory, open 'config.json'</samp>
看起来正常,但一旦内容变长或嵌入表格/弹性布局,换行行为不可控。正确做法是:
<pre class="brush:php;toolbar:false;"><samp>Error: ENOENT: no such file or directory, open 'config.json'</samp>
负责保留格式(换行、空格、Tab),<samp> 负责声明语义(这是输出)</samp>
- 禁止嵌套
:<pre class="brush:php;toolbar:false;"><samp>...</samp>
—— W3C 明确不推荐,辅助技术可能跳过 层 - 如果输出含 ANSI 颜色码(如 \x1b[31mERROR\x1b[0m), 不解析,得靠 JS 渲染或改用专用库
敏感信息、伪输出、截图转文字一律不用
这是最容易翻车的边界场景:
- 把
API_KEY=sk-xxx 放进 <samp> —— 源码可见,毫无遮掩,且语义错误(这不是输出,是配置)</samp> - 把 Postman 截图里的响应体 OCR 成文字再包 —— 缺失真实上下文,屏幕阅读器会误读为“终端输出”
- 文档里写“假设返回如下”,然后跟一段 JSON —— 这是示例,不是样本,该用
aria-label="模拟响应示例"+ - 服务端日志(如
2026-04-27T01:03:00Z INFO app started)❌ —— 日志是记录,不是用户代理呈现的输出, 不适用
真正难的从来不是怎么写 ,而是敢不敢在写之前问一句:这段文字,此刻有没有真实地、未经加工地、出现在某个用户眼前的终端或控制台里?没有,就别用。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











