配置esbuild支持CSS Modules与Sass/Scss失败，求调试及解决方案

背景 #

我正在尝试扩展esbuild的CSS支持，让它兼容CSS Modules和Sass/Scss，所以用了基于esbuild插件API的自定义插件。一开始试了：

• esbuild-sass-plugin：负责处理.scss文件的解析/转译，但不支持CSS Modules（尽管宣传说有扩展性）。

为了补全CSS Modules支持，又加了另一款esbuild插件：

• esbuild-css-modules-plugin：同样无法提供有效的CSS Modules支持。

相关技术版本 #

• Node：14
• esbuild：^0.11.11
• esbuild-css-modules-plugin：^2.3.2
• esbuild-sass-plugin：^2.2.6
• sass：^1.53.0
• typescript：^4.2.3

我需要的帮助 #

• 怎么高效调试这些插件无法正常支持CSS Modules的问题？
• 我忽略了哪些关键点，这些盲区是因为什么认知缺口导致的？

相关代码片段 #

package.json - 相关构建脚本 #

"build:dev": "node build.js esbuild-browser:dev"

build.js（esbuild入口文件） #

const sassPlugin = require("esbuild-sass-plugin").default;
const cssModulesPlugin = require("esbuild-css-modules-plugin");

let options = {
  bundle: true,
  minify: true,
  minifyWhitespace: true,
  sourcemap: true,
  target: "es2018",
};

let builds = {
  "esbuild-browser": () => ({
    ...options,
    platform: "browser",
    format: "esm",
    sourcemap: "external",
    outfile: "build/esbuild/browser.js",
    entryPoints: ["src/browser.ts"],
    plugins: [sassPlugin()],
  }),
  "esbuild-browser:dev": () => ({
    ...options,
    watch: true,
    platform: "browser",
    format: "esm",
    outfile: "build/esbuild/browser.js",
    entryPoints: ["src/browser.ts"],
    plugins: [sassPlugin(), cssModulesPlugin()],
  }),
};

require("esbuild")
  .build(builds[process.argv[2]]())
  .catch(() => process.exit(1));

ScrawlComponent.tsx（注意<span/>的className） #

import React from "react";
import styles from "./styles.scss";

type Props = {
  content: string;
};

const ScrawlComponent = (props: Props) => {
  const { content } = props;

  return (
    <span
      id="animation_link_target_text"
      className={styles.animation_link_target_text} 
    >
      {content}
    </span>
  );
};

export default ScrawlComponent;

输出HTML（注意<span/>缺失className） #

<html>
<head></head>
  <body>
    <div id="root"><span id="animation_link_target_text"></span> </div>
    <script src="./esbuild/browser.js"></script>
    <link rel="stylesheet" type="text/css" href="./esbuild/browser.css">
</body>
</html>

问题排查与解决思路 #

一、高效调试方案 #

1. 开启esbuild调试日志：在build配置中添加logLevel: 'debug'，查看插件执行顺序、文件处理流程，确认cssModulesPlugin是否真的处理了转译后的CSS文件。
2. 验证插件执行逻辑：在cssModulesPlugin中添加自定义钩子，打印处理的文件内容，确认是否接收到sassPlugin转译后的CSS输出。
3. 测试命名约定触发条件：把styles.scss改成styles.module.scss，修改组件导入路径后测试，多数CSS Modules插件默认只识别带.module后缀的样式文件。
4. 简化配置排除干扰：暂时关闭minify、sourcemap等非必要配置，单独测试cssModulesPlugin处理普通CSS文件的功能，确认插件本身是否正常。

二、你忽略的关键点及认知缺口 #

1. 插件数据传递逻辑：esbuild-sass-plugin默认会直接输出转译后的CSS文件，不会把内容传递给后续插件。需要配置transform选项，把转译后的CSS返回给esbuild，让cssModulesPlugin能拿到处理对象：

   sassPlugin({
     transform: async (css) => {
       return { css }; // 将转译后的CSS返回，供后续插件处理
     }
   })
   

2. CSS Modules的命名规则：你使用的styles.scss不符合多数插件默认的触发规则（需带.module后缀），导致插件直接跳过处理。
3. 版本兼容性问题：你用的esbuild是0.11.x旧版本，部分新插件的API可能与旧版不兼容，建议升级到0.14+的稳定版本再测试。

内容的提问来源于stack exchange，提问作者slackermorris