在 CSS 中，给样式表添加注释只有一种标准语法：使用 /* 开头、*/ 结尾的块级注释。无论是单行说明还是跨多行的文字，都必须放在这一对符号之间。浏览器解析样式表时会把注释内容完全忽略，不参与选择器匹配，也不会生成任何 CSS 规则。注意这和 JavaScript 中的 // 行注释不同，原生 CSS 并不支持双斜杠注释，如果不小心把 JS 的注释习惯带进来，样式表可能直接解析失败。
下面从语法规则、实际用途、常见误区和工程化实践几个方面展开。注释虽然不会影响页面渲染结果，但它的位置和书写方式直接关系到样式表能否被正确解析，也影响后续维护效率。
一、CSS 注释的基本语法与解析规则
CSS 注释以 /* 开始，以 */ 结束，中间内容可以是任意文本，包括中文、英文、数字和符号。一个简单的单行注释写法如下：
/* 这是单行注释 */
.box {
width: 100px;
}
如果需要写较长的说明，也可以让注释跨越多行：
/*
* 组件：卡片
* 作者：前端团队
* 说明：用于首页信息流中的卡片容器
* 依赖：变量 --card-radius
*/
.card {
border-radius: var(--card-radius);
}
CSS 注释不允许嵌套。也就是说，当解析器遇到第一个 */ 时，注释就会结束。如果在注释内容里再写一个 /*，并不会产生嵌套层级，后面紧跟着的 */ 仍然会提前终止注释。例如下面的写法容易出现解析错误：
/* 外层注释 /* 内层注释 */ 这里已经不在注释内了 */
上面的示例中，注释在第一个 */ 处结束，后面的 这里已经不在注释内了 会被当成样式规则解析，而其后的 */ 又会让浏览器产生语法错误。因此注释内容里不能出现 */ 组合，也不建议使用类似嵌套的结构。
在解析层面，CSS 注释会被当作空白处理。这意味着只要原来可以出现空白的位置，通常都可以写注释。例如选择器和花括号之间、属性名和冒号之间、多个声明之间都可以插入注释。但要注意，属性值内部、url() 函数内部以及自定义属性名等位置，注释可能阻断原本连续的 token，导致值无法正确解析。这类细节会在后文单独说明。
二、注释在样式表中的常见用法
最典型的用法是在文件头部增加版权信息、作者、更新日期和文件说明。这类注释块通常放在样式表的第一行，方便任何接手的人快速了解文件用途。比如：
/* * 主站全局样式 * 作者：某某团队 * 包含：重置样式、布局系统、通用组件 */
但不能把注释放在 @charset 之前。根据 CSS 规范，@charset "UTF-8"; 必须是样式表的第一条内容，如果前面先出现注释，某些浏览器会忽略编码声明，导致中文字符乱码。正确顺序是先写编码声明，再写注释和其他规则。
另一种高频用法是给不同模块做分区标记。大型样式表中，用醒目的注释分隔布局、组件、页面、工具类等区域，可以快速定位代码。比如：
/* ========== 布局系统 ========== */
.container {
max-width: 1200px;
margin: 0 auto;
}
/* ---------- 按钮组件 ---------- */
.btn {
padding: 8px 16px;
}
这种分区注释通常配合统一符号，例如等号、短横线、星号等，形成视觉层次。团队内部可以约定标题级注释、区块级注释和普通说明注释的不同写法。
行内说明用于解释某一条规则为什么这样写，尤其适合记录那些看起来奇怪但经过验证的数值。比如：
.list {
/* Safari 15 下需要额外偏移 1px 才能对齐 */
transform: translateY(-1px);
/* 防止长单词撑破布局 */
overflow-wrap: break-word;
}
行内注释要尽量简短，只保留对当前规则有意义的解释。过多行内注释反而会增加阅读噪音，应该把背景信息放到模块区块注释中。
注释还可以临时禁用某条声明或整段规则，这在调试时非常有用。开发过程中不确定某个样式是否是问题来源时，可以先用注释把它屏蔽，刷新页面观察变化，而不是直接删除。例如：
.card {
/* width: 300px; */
width: 100%;
/* display: none; */
}
调试结束后，应及时清理不再需要的注释，避免代码里残留大量被注释掉的规则，造成版本管理上的混淆。
三、编写 CSS 注释的注意事项与常见误区
第一个容易忽略的问题是 @charset 与注释的顺序。如前所述，编码声明前不能出现任何注释或其他规则。实际上 @charset 还有一个特殊要求：它只能出现在样式表顶部，并且只能出现一次。如果在它前面写注释，可能触发浏览器的兼容模式，导致整个文件按错误编码读取。因此，需要声明字符集时，第一行必须是 @charset "UTF-8";，注释放在它之后。
第二个误区是把注释插进属性值内部。虽然 CSS 注释可以替换空白，但属性值往往由多个 token 组成，注释会切断 token。例如下面的写法虽然有可能被浏览器宽容处理，但并不推荐，而且很可能直接失效：
.box {
color: /* 红色 */ red;
background: url(/* 图标 */ icon.png) no-repeat;
}
color 中的注释通常可以解析，因为 red 是一个独立 token；但 url(/* 图标 */ icon.png) 会把 url() 内部的地址写成两段，一些浏览器可能无法正确识别。更安全的做法是把注释放在声明外部，或直接放在属性值之后：
.box {
/* 主色使用红色 */
color: red;
/* 背景图标来自 assets 目录 */
background: url(icon.png) no-repeat;
}
第三个误区与压缩工具有关。很多构建流程会把 CSS 中的常规注释全部删除，以减小文件体积。但有些注释需要保留，例如版权声明、许可协议、构建信息等。CSS 压缩工具通常支持一种特殊注释写法：以 /*! 开头。这类注释在压缩时默认保留。比如：
/*!
* 组件库样式 v1.0.0
* 版权归某公司所有
*/
.btn {
display: inline-block;
}
使用 PostCSS、clean-css、cssnano 等工具时，可以配置保留规则。如果希望某些注释一直保留到生产环境，应该使用 /*! 形式，并了解所用工具的具体行为。
第四个误区是在注释中写敏感信息，比如密码、调试接口地址、内部路径或员工姓名。注释虽然不影响运行，但会在源码和浏览器开发者工具中可见。如果样式文件被部署到公网，任何人都可以通过查看源码读取这些注释。因此，注释内容也要经过信息安全意识过滤，不要因为它是注释就放松警惕。
四、预处理器与工程化环境中的注释策略
在 SCSS、Less 等预处理器中，注释规则比原生 CSS 更丰富。SCSS 支持两种注释：块注释 /* */ 和行注释 //。其中 // 注释在编译为 CSS 时会被完全移除，而块注释则取决于编译选项。例如：
// 这是 SCSS 行注释，编译后不会出现在 CSS 中
$brand-color: #3366ff;
/* 这是块注释，默认可能保留 */
.button {
color: $brand-color;
}
如果项目大量使用 SCSS 或 Less，需要明确注释策略：哪些用于开发者阅读，哪些需要保留到编译后的 CSS 中。对于只服务于源码阶段的说明，使用 // 可以减少最终文件体积。
现代 CSS 工程化还常结合 stylelint 等工具管理注释规范。stylelint 可以通过配置要求某些模块前必须有注释，或者限制注释的格式。例如团队规定每个文件头部必须有描述性注释，每个单独组件必须带有作者和用途说明。这样可以在 CI 阶段自动检查，避免注释逐渐缺失。KSS 或 SassDoc 等文档生成工具还能从注释块中提取结构化信息，自动生成样式规范文档。
命名规范和注释风格最好一起约定。比如推荐使用统一的注释模板：
/* * 模块：xxx * 作者：xxx * 用途：xxx * 依赖：xxx */
也可以使用类似 JSDoc 的标签形式，例如 @author、@version、@deprecated 等。这样做虽然单次编写成本略高，但长期来看能显著降低多人协作时的沟通成本。尤其当样式表规模超过数千行时，结构化注释的价值会非常明显。
另外，CSS 注释还可以配合第三方工具生成 source map 或进行样式隔离说明。部分构建工具会在样式文件头部注入版本号、构建时间等信息，这些信息常以保留注释的形式存在。开发时需要区分自动生成的注释和手写注释，不要混淆来源。合理使用注释能让 CSS 从单纯的一堆规则，变成有结构、有上下文、可维护的样式资产。
CSS 注释语法简单，但真正用好需要理解解析规则、位置限制和构建流程。用块注释记录关键信息，用分区注释组织大型样式表，用行内注释解释特殊规则，同时避免在 @charset 前、url() 内或属性值中间随意插入注释。这样就能在可读性、可维护性和构建产物体积之间取得平衡。