质量控制实战：前端项目中那些你必须掌握的检测与优化技巧

前端质量控制，到底该用哪种方案？

最近项目上线后被 QA 抓了一堆 UI 一致性问题，比如按钮圆角不统一、颜色用了十几种、间距忽大忽小。我意识到光靠 Code Review 和口头约定根本挡不住这些“视觉污染”。于是花了一周时间，把几种主流的前端质量控制方案都试了一遍：Stylelint、ESLint + 自定义规则、Design Token + Storybook。今天就来聊聊我的真实体验，不讲大道理，只说踩坑和实用感受。

谁更灵活？谁更省事？

先说结论：我比较喜欢用 Design Token + Storybook 这套组合拳，但不是所有团队都适合。如果你是小团队或者快速迭代的项目，Stylelint 可能更省事。下面一个个拆开说。

先看 Stylelint。它对 CSS/SCSS 的约束力很强，写个配置就能强制规范命名、单位、颜色值等。比如禁止使用 px（除非是 1px 边框），强制使用设计系统里的色板：

// stylelint.config.js
module.exports = {
  rules: {
    'unit-disallowed-list': ['px'],
    'color-named': 'never',
    'plugin/no-unsupported-browser-features': true,
    // 强制使用设计系统色板
    'csstools/value-no-unknown-custom-properties': [
      true,
      {
        importFrom: './src/tokens/colors.css',
      },
    ],
  },
};

这玩意儿在 CI 里跑一下，基本能挡住 80% 的低级错误。但问题是：它只能管“怎么写”，管不了“写什么”。比如你定义了 --color-primary: #3b82f6，但有人偷偷用了 #3b82f5，Stylelint 根本发现不了。而且一旦设计系统改了主色，你得手动全局替换，很容易漏掉。

核心代码就这几行？别信！

后来我尝试用 ESLint 写自定义规则，想从 JS 层面拦截非法的颜色或尺寸。比如检测是否使用了非设计系统的颜色值：

// eslint-plugin-design-system.js
module.exports = {
  rules: {
    'no-raw-colors': {
      create(context) {
        return {
          Literal(node) {
            if (typeof node.value === 'string' && /^#[0-9a-f]{6}$/i.test(node.value)) {
              context.report({
                node,
                message: '禁止直接使用十六进制颜色，请使用 designSystem.colors.xxx',
              });
            }
          },
        };
      },
    },
  },
};

想法很美好，但实际用起来巨麻烦。JSX 里写内联样式、CSS-in-JS、styled-components、普通 CSS 文件……每种都要单独处理 AST 节点。折腾了两天，只覆盖了 60% 的场景，剩下的 edge case 太多。而且团队里新人看到 ESLint 报错一脸懵：“为啥不能写 #fff？”——工具太底层，沟通成本反而更高。

Design Token + Storybook：真香但门槛高

最后我回归到设计系统本身。把所有可复用的设计变量抽成 Design Token（JSON/YAML 格式），然后通过构建工具生成 CSS 变量、JS 对象、iOS/Android 资源：

// tokens/colors.json
{
  "color": {
    "primary": { "value": "#3b82f6" },
    "secondary": { "value": "#64748b" },
    "background": { "value": "#ffffff" }
  }
}

配合 Storybook，每个组件都展示在不同 Token 下的效果。开发时直接 import token，而不是写死值：

// Button.jsx
import { colors } from '../tokens';

const Button = () => (
  <button style={{ backgroundColor: colors.primary }}>
    Click me
  </button>
);

这套方案最大的好处是：从源头上杜绝了“自由发挥”。设计师改个主色，只要更新 Token 文件，整个项目自动同步。而且 Storybook 能直观看到组件在各种主题下的表现，QA 也能直接参与验收。

但缺点也很明显：前期投入大。要搭 Token 管理流程、写转换脚本、维护 Storybook。小项目可能还没上线就累死了。另外，如果团队没有设计系统意识，光靠前端推很难落地。

踩坑提醒：这三点一定注意

• 别指望工具 100% 拦截问题。我们用了 Stylelint 后，还是有人用 !important 覆盖样式。后来加了 ESLint 规则禁止 !important，结果又有人用 style= 内联绕过。最后只能靠 Code Review + 团队文化。
• Token 别过度抽象。见过有人把 spacing-sm、spacing-md、spacing-lg 拆成 10 个层级，结果开发根本记不住，干脆自己写 margin: 12px。建议初期只保留 3-4 个基础间距，够用就行。
• Storybook 别变成摆设。我们一开始建了 Storybook，但没人维护，两周后组件文档就过期了。后来改成 PR 必须包含 Storybook 更新，才勉强维持住。

我的选型逻辑

现在我给团队的建议很明确：

• 小项目 / 初创团队：直接上 Stylelint，配个基础规则集，5 分钟搞定。别折腾 Token，先活下来再说。
• 中大型项目 / 有设计系统：必须上 Design Token + Storybook。虽然前期累，但长期收益巨大。我们改完后，UI 一致性问题减少了 90%，设计师再也不用追着前端改颜色了。
• 混合技术栈（React + Vue）：Token 用 JSON 存，各端自己解析。避免用 JS 对象，否则 Vue 项目还得装 Babel。

至于 ESLint 自定义规则？除非你有专职的工具链工程师，否则别碰。维护成本太高，ROI 太低。

最后一点真心话

其实没有完美的方案。我们现在的系统里，Stylelint 依然在跑，用来 catch 一些 Token 覆盖不到的角落（比如第三方库的样式）。Storybook 也偶尔会漏更新。但整体上，用 Design Token 作为唯一真相源，是最可持续的做法。

以上是我踩坑后的总结，希望对你有帮助。如果你有更好的方案，比如用 Figma Tokens 自动同步到前端，欢迎评论区交流！