企业官网建设流程全解析

接手别人的老项目时，你可能也遇到过这种场面：打开一个几千行的CSS文件，选择器一串接一串，左右翻页找某个样式不知道它在哪，想改一个按钮颜色却要先花半小时“考古”。这时候你大概率会在心里骂一句：当初写这些样式的人，怎么就不知道写点注释呢？

我在前端这条路上混了十来年，写过、也接手过大量样式代码。一个很现实的规律是：几乎所有难维护的CSS，都不是因为开发者的水平不行，而是因为注释体系彻底缺失。CSS不像JavaScript那样有清晰的函数边界和变量名，一个.class名本身说明不了太多事情，如果不靠注释把“意图”标出来，那整个文件就是一个没有目录的长篇小说。

关于“CSS的注释”，这篇文章我想认真聊一聊。不是那种“注释就是/* 你好 */”的入门科普，而是从语法细节、信息架构、调试技巧、构建工具处理，到一套可以直接拿去用的团队注释规范，把注释这件事讲透。

1. 没写注释的CSS文件，读起来有多绝望

先说个真实场景。有一年我接手一个做了三年的后台管理系统，光样式文件就有十多个，单个文件最大的一万多行。同事交接时说“样式基本不用改”，结果第一个需求就是调整侧边栏的宽度。

我打开sidebar.scss，看到的是这样的长龙阵：

.aside { width: 240px; float: left; } .aside .logo { padding: 20px 0 20px 16px; } .aside .logo img { width: 36px; height: 36px; } .aside .menu { margin-top: 20px; } .aside .menu li { list-style: none; height: 44px; line-height: 44px; } ...

没有文件头说明，没有区块分隔，没有一行文字说明“这个宽度为什么是240”“margin-top的20px是在给谁让位”。我想把240px改成220px，但完全不敢确定有没有其他样式依赖这个数值。最后只能全局搜索、逐个试，改完再回归测一遍。

类似经历多了以后，我对CSS注释的态度特别明确：注释不是写给浏览器看的，是写给下一个维护者看的，而那个下一个维护者大概率是三个月后的自己。

1.1 CSS对注释的需求比JS更迫切

JavaScript代码哪怕没有注释，你看到函数名、参数名，至少能猜个大概。但CSS是纯声明式的，一个规则块里只有“选择器 + 属性 + 值”，没有执行逻辑，也没有中间变量。它背后的设计决策——比如“为什么用flex而不是grid”“为什么这个元素要position: absolute”“为什么z-index是99”——如果不写下来，后来的人只能靠猜。

CSS的选择器也带不来太多语义。.list-item:nth-child(2n) .badge到底作用在哪个业务模块上？如果当初不在上面注释“订单列表的等待中标签”，光看这个选择器，神仙也联想不到。

我把CSS注释分成两个层面看：

• 技术层面：说明这个样式“做了什么”。
• 业务层面：说明这个样式“为什么存在”。

两者缺一不可。只写“这里的宽度是240px”等于没写，因为代码本身就写明白了；真正值钱的是“因为侧边栏要容纳320px的折叠面板，且与内容区保持24px间距，所以净宽240px”。

1.2 不写注释的隐性成本

有团队觉得，注释是额外的活儿，耽误进度。但算一笔账就明白了：写一行注释平均要不了半分钟，而一个完全没有注释的样式文件，后人来排查一个属性为什么生效、被哪里覆盖，可能要多花半天。半个月后你自己回来看，也得重新读一遍代码。

隐性成本不只体现在排错。没有注释的CSS，会催生两种恶性行为：

• 不敢改：因为看不懂意图，只能不断往上叠新样式，代码越积越多，形成祖传屎山。
• 乱改：看不懂但赶时间，直接删掉觉得“多余”的规则，结果布局崩了，再花两小时排查。

这两种我都经历过。说句实在的，一个项目的样式好不好维护，就看你愿不愿意花那半分钟写注释。

2. CSS注释的语法底线与浏览器处理细节

注释的语法本身很简单，但有一些细节是很多人不知道的，这些坑能坑到最掉以轻心的时候。

2.1 基本写法：/* 和 */ 成对出现

CSS中，注释以/*开头，以*/结尾，可以跨多行，可以放在任意两个有效表达式之间：

/* 这是单行注释 */ body { /* 注释写在普通位置 */ margin: 0; padding: 0; } /* 这段注释比较长， 写在第二行也完全没问题 */ .container { width: 1200px; /* 注释甚至能嵌在内容中，但建议别这么干 */ margin: 0 auto; }

从语法角度说，注释可以出现在两个token之间。比如选择器和花括号之间：

.article /* 这里是注释 */ { color: #333; }

这种写法浏览器不会报错，但可读性非常差，没有任何团队会推荐这么做。正常情况下，注释就放在样式规则上方或属性值后面。

2.2 最容易被忽略的硬规则：注释不能嵌套

CSS注释没有嵌套的概念。你写：

/* 外层注释 /* 内层又写了一个注释 */ . */

浏览器遇到第一个*/就认为注释结束了。上面的代码里，内层注释的*/会和外层开头的/*匹配，而后面的.和*/就变成了游离的垃圾内容，轻则被跳过，重则直接让后续样式失效。

这个坑很多人在临时注释大段代码时会踩到——想注释掉一大块包含注释的样式，前后各加/*和*/，结果中间那个*/提前“关门”了，露出大段未注释的代码，样式崩得稀里哗啦。

注意：在给你开发的CSS文件写注释时，如果只是想临时停用某个规则块，请先检查这个规则块内部有没有已有的注释。有的话，要么先删掉内部的注释，要么只注释需要修改的具体行，而不是整块套起来。

2.3 从解析器视角看，注释等价于空白

这一点说出来很多人会愣一下，但理解它，你就理解了很多“奇怪行为”。CSS解析器在处理注释时，并不把它当特殊节点，而是当作一种空白字符。这意味着：

• body/* 冷知识 */{ margin: 0; }和body { margin: 0; }解析结果完全一样。
• 注释和空格一样，只是用来“分开”不同token的，本身不会在计算样式里留下任何痕迹。

这带来一个实际指导意义：不要在注释里指望它能做到什么特殊事情。比如有人想用注释做条件逻辑，让某些浏览器只读取某段CSS——这是老IE时代的玩法了，现在完全行不通。注释就是被丢弃的东西。

2.4 CSS注释与HTML注释的区别

做前端的人经常在HTML和CSS之间切换，很容易搞混注释语法。在HTML文档里：

<!-- 这是HTML注释 --> <style> /* 这是CSS注释 */ .btn { color: red; } </style>

HTML的注释是<!-- ... -->，CSS的注释是/* ... */。两者不能混用。

有一种历史遗留写法：在HTML里的<style>标签内，有人会用HTML注释包住CSS，防止老浏览器把CSS当文本显示：

<style> <!-- body { margin: 0; } --> </style>

这纯粹是上古时期的兼容手段，现在的浏览器早就把<style>内容按CSS解析了。如果你在维护老代码时见到这种，放心把<!-- -->去掉，改成正常的/* */注释即可。

2.5 注释里的特殊字符与编码

CSS注释中可以包含中文、英文、emoji、各种符号。理论上没有任何字符限制，只要不包含*/。但有两件事值得留意：

• 在CSS文件编码为UTF-8时，中文注释没问题；但如果文件是ISO-8859-1等编码，中文注释可能乱码。建议所有CSS/SCSS文件统一UTF-8。
• 注释里别使用生僻的Unicode符号或特殊换行符，某些旧版压缩工具会处理出问题，保持纯文本最稳妥。

3. 用注释把样式表搭出信息架构

注释有一个特别容易被低估的用途：组织信息层级。一份几千行的CSS一旦有了好的注释骨架，阅读体验完全不一样，就像一本书有了目录和章节标题。

3.1 文件头注释，介绍整份文档

每个CSS文件顶部，建议放一个文件级注释块，写明文件用途、适用平台、维护注意事项。实用的写法不需要花哨，但信息得精准：

/* ========================================================================== 全局基础样式表 用途：站点全局reset、基础字体、栅格变量 适用：全部页面（不含后台管理系统） 维护：前端组 张某某 最近调整：2024-03-12，新增移动端断点变量 ========================================================================== */

有人会觉得“维护：张某某”这种信息放在注释里容易过时，我理解这种担心。所以我现在倾向于不写具体维护人，而是写“该文件全局共享，改动需通知前端所有人”。但文件用途和改动级别这种信息一定要有，它会直接影响后来的人“敢不敢动这个文件”。

3.2 目录式注释与区块标题

大型样式表的核心组织手段是“分区块+区块标题”。我习惯用这样的格式：

/* ========== 11. 页面组件区（Buttons / Cards / Modals） ========== */ /* ---------- 11.1 基础按钮 ---------- */ .btn { display: inline-block; padding: 8px 16px; border-radius: 4px; } /* ---------- 11.2 按钮变体 ---------- */ .btn-primary { background: #1677ff; color: #fff; }

如果文件尤其大，还可以在最顶部放一段“目录注释”，把区块顺序列出来：

/* ========== 目录 ========== 01. Reset与全局变量 02. 布局骨架 03. 顶部导航 04. 侧边栏 05. 内容区通用模块 06. 表格与表单 07. 弹窗组件 08. 响应式与断点覆盖 ========== 目录结束 ========== */

目录注释的价值不在于它能“点击跳转”（它没有超链接功能），而在于让阅读者对自己所处的位置有全局认知，知道某个样式应该在哪个区块找。这对新接手项目的人特别友好，能够有效缩短熟悉时间。

3.3 属性级注释，回答“为什么”

全局层面有了结构，接下来就是单个规则里的属性注释。基本原则：只注释有故事的地方。

一个例子：

.card { /* 内边距用16px而不是12px：为了和下方文字行高保持视觉对齐 */ padding: 16px; /* 避免极端字号环境下内容溢出，等比缩放到最小150px */ min-width: 150px; /* 圆角之所以用6px，和全局控件的半径变量统一 */ border-radius: var(--radius-md); }

这种注释写的不是“padding是16px”——代码里明明白白写着了——而是解释这个值是“怎么来的、为什么用这个值”。很多时候这些决策是设计师定的、是测试反馈的、是针对某个特定bug打补丁的，不写下来就永远丢失了。

我也见过反面案例，属性旁边全是废话：

/* 背景色 */ background: #fff; /* 字体大小 */ font-size: 14px;

这种注释和没写一模一样，还多了一堆噪音。我看到团队里有人这么干一定会提醒：注释至少得说出代码看不出的信息，否则删掉。

3.4 版本与版权类注释

如果你在写开源项目或公用组件库，/*! ... */这种注释格式值得了解：

/*! * UI组件样式库 v2.4.0 * Copyright (c) 2024 XX公司 * Licensed under MIT */

上面这个/*!有一个特殊作用：绝大多数CSS压缩工具会默认保留这个样式的注释。比如cssnano、clean-css，处理时会移除普通注释但留下/*!开头的块。这也解释了为什么你在很多CDN的min.css文件顶部能看到完整版权声明。如果你有不想被压缩掉的注释，就给开头加个感叹号。

4. 调试时怎么用注释提高效率

注释不仅是“写给别人看的文档”，它还是排错时极其好用的工具。我自己的经验，调试CSS时第一手段不是删代码，而是“注释掉代码”。

4.1 临时禁用的标准流程

假设某个元素样式异常，你怀疑是某一行属性导致。最直接的做法是：

• 在DevTools的Styles面板里点掉属性前的复选框。
• 如果你在源码里排查，就使用注释把可疑属性或规则块包起来。

在源代码层面注释掉整块规则是这样：

/* .product-grid { display: grid; grid-template-columns: repeat(3, 1fr); } */

注释之后刷新页面，观察布局变化。如果问题消失，说明就是这个规则的问题；如果还在，恢复注释，换下一个目标。

这个做法的好处在于可逆。删代码很容易，但反悔就麻烦了，尤其改到一半发现删掉的规则有其他作用。注释允许你随时恢复。

4.2 那个让我记忆犹新的z-index排查

有一年排查一个弹窗被遮挡的问题。我打开线上代码，发现弹窗的z-index是99，但始终被另一个区块压在下面。同事跟我说“注释大法好”，逐行注释，终于定位到问题所在——侧边栏的transform属性创建了新的层叠上下文，不是z-index不起作用的问题。

这个例子说明，调试时通过注释“排除法”定位问题，效率很高。但还有一个关键教训：排查完成后，临时注释的代码要及时清理。要么恢复、要么彻底删除，别留着几大段注释掉的代码块过年，时间一长没人知道它们为什么被注释，也不敢删。

4.3 用注释给未来留信号：TODO/FIXME/优化标注

调试过程中发现的潜在问题，可以顺手用注释标记下来：

.banner { position: relative; /* TODO: 待替换为新的渐变方案，旧样式先保留到v2.8上线 */ background: linear-gradient(...); /* FIXME: IE下该元素的圆角不生效，后续考虑用clip-path */ border-radius: 12px; }

这种注释不只是给自己看的，也是给队友的信号。IDE会高亮它们，代码搜索也能快速定位。要注意的是，这些标记必须有补充说明——光是“TODO”三个字母没有意义，必须写清楚“待做什么、为什么待”。

4.4 警惕：注释掉的内容也会误导人

前面说注释可逆方便调试，但这里就有一个反面副作用。被注释掉的代码还停留在源码里，很容易让后人误以为“这个样式还在生效”，于是排查半天找不到原因。

我的经验是：

• 临时注释的代码，尽量当天处理完：要么恢复，要么加一个删除deadline，要么直接删除。
• 被注释的规则如果具有一定的参考价值（比如旧方案说明），就在注释块里额外写一句“该方案已废弃，勿需恢复”。
• 实在想留作历史参考，我会更建议移出版本库的历史提交去看，而不是留在活跃代码里。不过具体取舍看团队的接受度。

5. 预处理器、压缩工具和注释的存活规则

CSS开发早就不是“写一个纯css文件”那么单一了。你在项目里用SCSS、LESS，会经过编译；使用打包工具，会经过压缩。注释在这些环节里到底会被怎么样，很多人没搞清楚，导致写了半天注释发布后“人间蒸发”。

5.1 SCSS/LESS的注释差异

SCSS中的注释有两种语法，命运完全不同：

// 这种注释在编译后就没了，只存在源码中 /* 这种注释会原样输出到编译后的CSS */

也就是说，SCSS中使用//写的注释，只服务于开发阶段的开发者；而/* */写的注释，会跟着进入生成的CSS文件，后续还可能被压缩工具二次处理。

想清楚“这条注释是给谁看的”来决定用哪种写法。比如“这段样式是为了绕开某个旧浏览器的bug”这种注释，就应该用/* */，因为它对阅读编译产物的人也有价值。而“这里用了mixin，参数含义见functions.scss”这种，只对源码读者有用，用//即可，减少生产文件体积。

5.2 压缩工具默认吃掉普通注释，但保留带感叹号的

目前主流的CSS压缩工具（cssnano、clean-css、esbuild/terser的CSS处理部分）默认行为高度一致：

• 删除所有普通注释，包括/* ... */。
• 保留以/*!开头的注释。

所以当你需要保证某些注释在意料之外的文件里存活，比如压缩交付给客户并带有版权信息时，就要养成写/*! */的习惯。在构建配置里也可以控制。

以cssnano为例，它的discardComments选项允许指定保留规则：

cssnano({ preset: ['default', { discardComments: { removeAll: false, remove: comment => comment.includes('license') || comment[0] === '!' } }] })

在webpack或Vite配置里按需调整，我不建议照搬乱配，但要知道有这个能力。

5.3 构建配置举例：保留指定注释

很多团队会把“注释里的信息”当成文档的一部分，比如颜色变量对照表、设计规范链接。若用真实项目配置举例，可按以下逻辑写在postcss.config.js里：

module.exports = { plugins: [ require('autoprefixer'), require('cssnano')({ preset: ['default', { discardComments: { remove: (comment) => { // 保留包含“spec:”前缀的注释，比如“spec: 颜色变量见设计规范第4页” return !comment.startsWith('spec:'); } } }] }) ] };

这类配置的意义在于：构建处理时，注释的存亡不是随缘，而是你有意识地筛选。普通备注被清掉可以帮线上CSS减重，但关键的业务说明要保留。

5.4 现代CSS方案里，注释的位置变了

Tailwind、CSS Modules、CSS-in-JS这些方案近年大为流行，它们对注释提出了新的问题：

• Tailwind生成的CSS文件极长，且大部分由框架生成，手工注释意义不大。注释更多出现在配置文件和组件里。
• CSS Modules的类名会hash，源码中的注释不会影响编译结果，所以写在源文件里的/* ... */仍然有效。
• CSS-in-JS（如styled-components、Emotion）中，样式是JS字符串，注释直接以字符串内的形式出现。这种情况下注释能随着组件被复用，更像组件级文档。

如果是新项目用这些方案，注释的存活逻辑不同，但本质不变：注释的位置跟着源码走，只要源码在技术团队手中，它就还是有价值的。

5.5 注释还能驱动文档生成

可能有人不知道，注释可以通过工具自动生成样式文档。KSS这个规范就是典型代表：在注释里按固定格式写说明、示例，工具会自动提取成类似“组件市场”的文档页面。

/* Button——可点击的操作按钮 .button--primary - 主要按钮（蓝色底） .button--default - 默认按钮（灰色底） Markup: <button class="button {{modifier_class}}">按钮</button> Styleguide 1.1 */ .button { display: inline-block; padding: 6px 12px; }

如果团队重视组件化文档管理，这比“每个组件手写一份MD文档”要省事得多——注释和代码永远放一起，改代码时顺带改注释，文档不会过期。

6. 值得长期使用的一套CSS注释规范

讲了这么多原理和场景，最终要落到一个可执行的规范。我之前深度参与的组件库项目，团队里最终沉淀出一套注释约定，现在分享出来给你直接参考。

6.1 注释分成四个层级

这四级的命名我并不要求每个团队都一样，但是这种分级思维建议保留。有了层级，注释就不会乱。

6.2 注释内容分类清单

具体讲，写注释时可以对照这四类“有效信息”：

1. 为什么用这个值：比如padding: 16px;背后是栅格变量的整数倍。
2. 为什么这个元素要这样布：比如position: absolute是相对于哪个父级定位，需要注意什么。
3. 这个写法兼容了什么：比如针对某个浏览器版本的bug workaround。
4. 有什么联动影响：比如这个类被JS或者另一个组件引用，改动会波及哪些地方。

我建议团队里对“什么注释没必要写”也达成共识：直接重复代码内容的注释、纯模板化的作者/日期头、大段被注释掉的死代码，能不用就不用。

6.3 一个可直接抄的文件结构模板

实践下来，如下样式的文件结构能兼顾“信息完备”和“视觉简洁”：

/* ========================================================================== 用户中心模块样式 适用页面：/user/profile、/user/settings 说明：本文件所有样式仅作用于用户中心路由下的组件 注意：不要在这里添加全局组件样式，全局样式统一放global/文件 ========================================================================== */ /* ---------- 0. 目录 ---------- 01. 通用用户卡片（01-90行） 02. 资料编辑表单（91-210行） 03. 头像上传组件（211-330行） 04. 消息中心列表（331-500行） ---------- 目录结束 ---------- */ /* ===== 01. 通用用户卡片 ===== */ .user-card { ... } /* ===== 02. 资料编辑表单 ===== */ .profile-form { ... } /* ===== 03. 头像上传组件 ===== */ .avatar-uploader { ... } /* ===== 04. 消息中心列表 ===== */ .message-list { ... }

目录注释里的行号会随着代码修改而变化，所以这个行号我建议只在初始建设时标，后续维护如果更新不及时就宁可去掉行号。

6.4 代码评审时的注释检查

最后一个插曲：我参与Code Review时，一定会看注释的质量。我会问三个问题：

• 这个文件有没有文件头？没有的话，我能不能从文件名判断出用途？（判断标准简单但有效）
• 这段选择器看起来莫名其妙的，有没有注释解释设计初衷？没有的话需要补。
• 有没有被注释掉的死代码？有，就要求删除或给出合理的保留说明。

有了评审环节把关，注释规范才能真正落地。否则写了规范不执行，等于没有规范。

如果你现在正在维护一个没什么注释的老样式文件，不用急着一次性补齐所有注释。我的建议是：先给文件补一个文件头注释，再把当前正在修改的模块加上区块注释。循着“改哪里补哪里”的节奏，几个月下来整个文件的注释覆盖率会肉眼可见地提高。至少，那个三个月后打开这个文件的自己，会感谢你手下留情。