该用 <kbd> 表示用户主动输入的键盘操作，<samp> 表示程序被动输出的结果，<var> 表示需替换的可变占位符；三者语义不同，混淆会损害可访问性与机器解析准确性。
什么时候该用 <kbd> 而不是 <samp>
<kbd> 表示用户**主动输入的键盘操作**，比如按键、快捷键、命令行输入；<samp> 表示程序或系统**被动输出的结果**，比如终端回显、错误信息、API 响应体。混淆两者会导致语义错误，影响可访问性（屏幕阅读器会读作“keyboard input”或“sample output”）。
常见误用场景：
- 把
Ctrl+C写成<samp>Ctrl+C</samp>—— 应该是<kbd>Ctrl+C</kbd> - 把终端报错
Permission denied包在<kbd>里 —— 应该是<samp>Permission denied</samp> - 在代码教程中写“运行
npm install”，其中npm install是你要敲的命令，用<kbd>npm install</kbd>；而它执行后打印的added 42 packages</samp>才用<samp>
<var> 不是变量名高亮，而是表示“可变内容占位符”
<var> 的本意是标记文档中**会被替换、计算或由上下文决定的实际值**，不是语法高亮工具。它常用于说明文档、手册、CLI 帮助文本中表示参数占位符，比如 git checkout <var>branch-name</var>，这里的 <var>branch-name</var> 暗示读者要替换成真实分支名。
容易踩的坑：
立即学习“前端免费学习笔记（深入）”；
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 在代码块里给
let count = 0中的count加<var>—— 错。这是变量声明，不是文档占位符；应直接用<code>包裹整行或用 CSS 高亮 - 用
<var>包裹数字或字符串字面量（如<var>"hello"</var>）—— 语义不清，除非你在写类似curl -X POST -d <var>{"key":"value"}</var> ...这种示意性请求体 - 和
<code>嵌套不当：正确是<code>git push origin <var>main</var></code>，而不是<var><code>main</code></var>
浏览器默认样式差异小，但语义影响可访问性和 SEO
三者默认都显示为等宽字体，视觉上难区分，但浏览器和辅助技术依赖标签含义做处理：
-
<kbd>在部分屏幕阅读器中会读作 “keyboard input”，并可能触发特殊音效 -
<samp>可能被爬虫识别为“示例输出”，影响技术文档片段提取 -
<var>几乎无默认样式，常需配合 CSS（如font-style: italic）增强可读性，但加样式不能替代语义 - 不要为了“看起来像命令行”就滥用
<kbd>套整个命令行片段（如<kbd>$ ls -la</kbd>）——$是提示符，不是用户输入；应拆成<span>$</span> <kbd>ls -la</kbd>或更严谨地用<code>+ CSS 模拟
嵌套组合才是真实使用场景
纯单标签很少见，实际文档中常嵌套使用来表达完整交互链路：
<p>按 <kbd>Ctrl+Shift+I</kbd> 打开开发者工具，在 Console 中输入：</p> <pre><code><kbd>console.log(</kbd><var>document.title</var><kbd>)</kbd></code></pre> <p>将看到输出：</p> <p><samp>"My Website"</samp></p>
注意点：
-
<kbd>只包真正敲击的部分（console.log()是你输的），不包<var>占位符 -
<var>必须出现在<code>或<pre>内才有意义，单独在段落中用易被忽略 - 避免三层以上嵌套（如
<kbd><code><var>...</var></code></kbd>），可读性与维护性会下降
语义标签的价值不在视觉，而在让机器（和人）准确理解“谁在操作、什么被输出、哪部分是变量”。写得越准，后期做自动化提取、无障碍适配、甚至 AI 辅助阅读时，出错概率就越低。
