Johnson
``` 产品说要多加几个人名，于是你多复制了几行 ```htmlJohnson
Rory
Jenifer
Sam
``` 怎么办？好像有点冗余，Tailwind 给了一个 [@apply 用法](https://v3.tailwindcss.com/docs/reusing-styles#extracting-classes-with-apply)，你可以这么写，把一些固定的预设放到一个类下面： ```htmlJohnson
Rory
Jenifer
Sam
``` ## 问题来了：Tailwind @apply 用法失效 最近，业务的同事反馈：有谁改过 tailwind 的配置吗？现在只要写 @apply 都会报错，怎么办？ 报错如下，直接导致编译失败 + 组件渲染失败：  看到这个报错，一瞬间，脑海中无数可能的疑点飘过： 1. 此大型项目是微前端架构，是某个子应用有问题，还是全部都有问题呢？ 2. Tailwind 的集成需要两个关键配置文件，`tailwind.config.js` 和 `postcss.config.js`，这两个配置，最近是否有人修改？ 3. Tailwind 还需要在项目的全局/公共 CSS 位置写入 `@tailwind utilities` 才能使用那一系列的预设工具类，会不会少了这个引入？ 4. 从报错的信息来看，应该是 Tailwind 不认识这个 `bg-red-400` 了，会不会少引入了什么，导致 Tailwind 做处理的时候，取不到这些预设对应的规则？ 以上这些都是猜想，我们一步一步来证实/证伪。 ## 初步排查：范围/配置/变更 首先，我选用了同一个微前端大仓下的其他子应用来测试，其中含有一个业务子应用，一个测试用的纯净子应用，发现都能 100% 复现该问题，说明**不是某个子应用的问题，而是所有子应用的共性问题。** 第二，我们看配置文件有没有被改过，这里用 `git log --since` 的方式取了过去 10 天内修改的文件名含有 tailwind/postcss 关键字的文件，发现只有 livemanage 一个子应用改过，并且变更内容其实是全新初始化了两份配置，不可能导致大范围的问题出现，所以**基本排除配置变更这个原因。**  第三点就很好验证，看了一下每个子模块的公共样式文件 `common.less` 都有引入 `@tailwind utilities`，**排除此原因**。 至于第四点，有没有可能是 tailwind 抽风，突然不认识那些简写（例如 `mb-12`）了呢？换句话说，有没有可能是 tailwind 的锅？ 首先，我们回头看一下这句报错， `The 'xxx' class does not exist. If 'xxx' is a custom class, make sure it is defined within a '@layer' directive.` 我们知道，[@layer](https://v3.tailwindcss.com/docs/adding-custom-styles#using-css-and-layer)是 Tailwind 提供的一种方便组织预设样式短名的能力，所以这句话看起来是 Tailwind 抛出来的，说明 **Tailwind 在处理这份样式的过程中确实有接手**。 另外，我们还发现，如果 @apply 后面只跟一条规则而不是多条，就不会有问题，类似这样： ```css .myClass { @apply mb-2; // 这样没问题 @apply mb-2 mx-1 bg-blue-100; // 连续多个有问题 } ``` 这进一步说明了，Tailwind 有接手处理，而且其实它也认识 `mb-2` 这些原子样式类，说明也不是原子样式类缺失的问题，更有可能是 **Tailwind 在提取/解析/切分 `@apply` 语句的时候出了问题**。 ## 缩小范围：tailwind 背锅？ 我们知道，任何华丽胡哨的样式文件最终产物不过都是 CSS 而已，Tailwind 之所以能够在样式文件里提供一些浏览器本身不支持的语法糖，意味着它必定要在得到最终 CSS 产物之前，把它的语法糖全部处理/转换成浏览器认识的样子，如下图，`mb-24` 要被转换为 `margin-bottom: 6em;`，其他以此类推。  那前端工具链里，什么工具能够方便地处理/转换 CSS 呢？那肯定是 [PostCSS](https://postcss.org/) 了。而且 Tailwind 也[确实是用了 PostCSS 插件来提供它的核心能力](https://github.com/tailwindlabs/tailwindcss/blob/main/packages/%40tailwindcss-postcss/package.json)。 所以，我们要看的是 Tailwind 如何基于 PostCSS 做样式替换的逻辑，实操上有个很方便的办法——用报错语句的静态部分来搜索。  找到下面这段代码（省略了无关的逻辑），可以看到，Tailwind 利用了 PostCSS 提供的 walk 能力，对于所有的 `@apply`，会调用 `extractApplyCandidates` 从中提取出所有的原子类，如果提取到的原子类不在 `applyClassCache` 中（也就是 Tailwind 不认识）的话，就会报这个错。 ```ts function processApply(root, context, localCache) { let applyCandidates = new Set(); // Collect all @apply rules and candidates let applies = []; root.walkAtRules('apply', (rule) => { // ... applies.push(rule); }); let applyClassCache = combineCaches([ localCache, buildApplyCache(applyCandidates, context), ]); for (let apply of applies) { // ... let [applyCandidates, important] = extractApplyCandidates(apply.params); // ... for (let applyCandidate of applyCandidates) { // ... if (!applyClassCache.has(applyCandidate)) { throw apply.error( `The \`${applyCandidate}\` class does not exist. If \`${applyCandidate}\` is a custom class, make sure it is defined within a \`@layer\` directive.` ); } let rules = applyClassCache.get(applyCandidate); // ... candidates.push([applyCandidate, important, rules]); } } // ... } ``` 看起来没什么毛病，会不会是提取的函数有问题呢？我们看看它的代码： ```ts function extractApplyCandidates(params) { let candidates = params.split(/[\s\t\n]+/g) if (candidates[candidates.length - 1] === '!important') { return [candidates.slice(0, -1), true] } return [candidates, false] } ``` 看起来没什么问题，如果一个 apply 有连续多个规则，通过空格/Tab/换行来切分，去掉最后可能的 `!important`。 例如，对于 `@apply mb-2 pb-3`，经过提取后，applyCandidates 应该是 `['mb-2', 'pb-3']` 那就奇怪了，我们直接加上打印语句，打印出来看看，拿到的 applyCandidates 长什么样：  好像有点诡异，为什么会有逗号？？？  难道 Tailwind 搞了什么骚操作吗？那我把入参打印一下：  什么？？Tailwind 接手的时候就已经有逗号了？？看来问题并没有这么简单。  ## 深入探索：Webpack Loader 追踪 曾试图把锅甩给 Tailwind，没想到，事到如今，我发现必须搞清楚这个问题，才会有答案： 我们写在 `.vue` 单文件组件（下文简称 SFC）里的 ` ``` 这时候 less-loader 就要站出来说了： **跟我没关系！你们去看我的代码，我只是包了一层，是 less 的问题！**  好吧，确实是 less 的问题。 （谁知道呢...一直没怀疑过 less，要是早点来这个 [Less Playground](https://lesscss.org/less-preview/) 试一下就好了） ## 原因总结 至此，问题的根源找到了： less 这个预处理器会把 @apply 后面的每个 keyword 之间加上一个莫名其妙的逗号，导致下一环节到 tailwind 的 postcss 插件接手的时候，按照空格/换行分割，得到的前面几个原子类都会多一个逗号（如 `mb-4,`），从而找不到对应的映射关系，无法做替换和注入，在 Webpack 的 postcss-loader 环节直接抛异常，导致模块编译无法继续进行，影响开发。 ## 为什么以前没事？ 还有一个疑问，项目中其实有大量 `@apply` 后面 follow 多个规则的写法，为什么之前没出问题，最近才出了问题呢？ 经验告诉我们，变更常常是导致问题发生的根源，肯定有什么东西发生了变更。 我直接打开 less 的源码仓库，处理 `@规则` 的代码就位于 `packages/less/src/less/tree/atrule.js` 五个月前，这里有一个可疑的变更：[fix(issue#4242): add support for layer at-rule](https://github.com/less/less.js/pull/4337)：  在他的 `CHANGELOG.md` 里搜索这个 PR 名，可以看到是 v4.4.0 版本加的这个 feature  到 Playground 切回 4.3.0 快速验证一下，果然。  ## 解决方法 1. 回滚 less 版本到 4.4.0 以前，可以使用 [pnpm.overrides](https://pnpm.io/9.x/package_json#pnpmoverrides) 根据作用域锁子依赖版本。 2. 如果不回滚，可以等待新版本修复，看到已经有修复 [PR](https://github.com/less/less.js/pull/4366/files) 了，尚未被作者合入主干 3. 如果不回滚也不等待新版本修复，可以用 `~""` 来包裹 @apply 后面的规则，例如 `@apply ~"mb-2 pt-3"` 这样，less就不会插入逗号，但缺点是写的时候可能IDE 会没有 Tailwind 的自动补全了 4. 如果上面的方案都觉得麻烦，项目赶着要上线，最快的方法是直接把 style 改成 `lang="css"`，这样就不会经过 less-loader ```json { "pnpm": { "overrides": { "less": "4.3.0" } } } ``` ## 排查技巧/原理总结 - 根据经验和工程化基础知识，猜测问题可能出现的原因有哪些，逐个猜想+证实/证伪 - 如果报错语句具有特征，可以直接搜索来定位 - 直接改 node_modules 是很有效的手段，但记得条件性打印 涉及到： - Vue SFC 的原理 - Webpack 的 loader 机制和执行顺序 - Tailwind 的作用原理 ## 参考 [彻底弄懂Webpack中的Loader机制](https://juejin.cn/post/7157739406835580965?searchId=20250914190226E1FE3BD8C0CA065C79ED) [Vue SFC Playground](https://play.vuejs.org/) [Less Preview](https://lesscss.org/less-preview/) [Webpack - Loaders](https://v4.webpack.js.org/loaders/)