feat: 使 runtimeCssImportRewriteLoader 总是在 postcss-loader 之前执行，而 runtimeClassSetLoader 在其之后执行

Author: sonofmagic

.changeset/loader-shunxu-tiaozheng.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+修正 runtime loader 的插入顺序，使 `runtimeCssImportRewriteLoader` 总是在 `postcss-loader` 之前执行，而 `runtimeClassSetLoader` 在其之后执行；同时新增调试日志和文档，方便排查 loader 链。

apps/taro-webpack-tailwindcss-v4/package.json

@@ -31,6 +31,7 @@
     "dev:qq": "npm run build:qq -- --watch",
     "dev:jd": "npm run build:jd -- --watch",
     "dev:harmony-hybrid": "npm run build:harmony-hybrid -- --watch",
+    "debug:loader-order": "cross-env WEAPP_TW_LOADER_DEBUG=1 taro build --type weapp --watch",
     "open": "weapp open -p",
     "postinstall": "weapp-tw patch"
   },

demo/webpack-loader-order-details.md

@@ -0,0 +1,32 @@
+# Webpack Demo Loader Execution Orders
+
+说明：Webpack 会按照 `module.loaders` / `rule.use` **从后往前**执行 loader。以下顺序均按“执行时的先后”列出，并特别标出 `postcss-loader`、`runtimeCssImportRewriteLoader`、`runtimeClassSetLoader` 所处位置。
+
+## native-mina
+- 路径：`demo/native-mina/webpack.config.js`
+- 执行序：`sass-loader → runtimeCssImportRewriteLoader → postcss-loader → runtimeClassSetLoader → file-loader`
+  - rewrite 在 PostCSS 之前；class-set 在 PostCSS 之后。
+
+## taro-app / taro-vue3-app / taro-webpack-tailwindcss-v4
+- 路径：`demo/taro-app/node_modules/@tarojs/webpack5-runner/dist/webpack/MiniWebpackModule.js`
+- 基础执行序：`preprocessor (sass/less/stylus) → runtimeCssImportRewriteLoader → postcss-loader → runtimeClassSetLoader → css-loader → MiniCssExtractPlugin.loader`
+  - 架构中的 `MiniCssExtractPlugin.loader → css-loader → postcss-loader` 的定义位于 `getCSSLoaders`，rewrite 和 class-set 分别在它们两侧。
+
+## mpx-app / mpx-tailwindcss-v4
+- 路径：
+  - Vue CLI loader 链：`demo/mpx-app/node_modules/@vue/cli-service/lib/config/css.js`
+  - Mpx 注入：`demo/mpx-app/node_modules/@mpxjs/webpack-plugin/lib/index.js`
+- 执行序（含 Mpx 注入后）：`preprocessor → runtimeCssImportRewriteLoader → postcss-loader → runtimeClassSetLoader → css-loader (被 wxss-loader 取代) → @mpxjs/wxss/loader → @mpxjs/style-compiler → MiniCssExtractPlugin.loader`
+  - rewrite 依旧在 `postcss-loader` 之前，class-set 在之后；Mpx 自身的 `wxss/style compiler` 仍保持在 css-loader 之后。
+
+## Uni-app (uni-app / uni-app-webpack5 / uni-app-webpack-tailwindcss-v4)
+- 路径：`demo/uni-app/node_modules/@dcloudio/vue-cli-plugin-uni/lib/chain-webpack.js`
+- 执行序：`preprocessor → runtimeCssImportRewriteLoader → postcss-loader → runtimeClassSetLoader → uniapp-preprocess (postcss 后再次注入) → css-loader → extract-css-loader / vue-style-loader`
+  - 在原链路中 `uniapp-preprocess` 会在 `css-loader` 前插入一次；rewrite/class-set 的插入仍然围绕 `postcss-loader` 对称。
+
+## Rax 示例（rax-app）
+- 路径：`demo/rax-app/node_modules/.pnpm/node_modules/build-plugin-rax-app/lib/userConfig/atoms/inlineStyle.js`
+- MiniApp 目标默认执行序：`preprocessor → runtimeCssImportRewriteLoader → postcss-loader → runtimeClassSetLoader → css-loader → MiniCssExtractPlugin.loader`
+  - 若 `inlineStyle` 强制开启，则 html/inline rule 会走 `preprocessor → runtimeCssImportRewriteLoader → postcss-loader → stylesheet-loader`（class-set 仍在 PostCSS 后）。
+
+> 备注：`runtimeCssImportRewriteLoader` 和 `runtimeClassSetLoader` 是全局注入的 runtime loader，只有在 Tailwind v4 且启用 rewrite 时才会-visible；其位置在所有 demo 中都遵循“rewrite-before-postcss / class-set-after-postcss”这一策略。

demo/webpack-style-loaders.md

@@ -0,0 +1,45 @@
+# Webpack Demo Style Loader Orders
+
+以下内容概览 demo 目录中所有基于 Webpack 的子项目，逐一列出样式相关 loader 的执行顺序以及配置来源（按 Webpack 实际执行顺序，即“数组尾部 loader 先执行”）。`
+` 表示同一条规则的连续 loader。
+
+## native-mina
+- **入口**：`demo/native-mina/webpack.config.js:30-52`
+- **SCSS**：`sass-loader → postcss-loader → file-loader`
+  - `sass-loader` 先将 `scss` 编译为 CSS。
+  - `postcss-loader` 接手做 Tailwind 等 PostCSS 处理。
+  - `file-loader` 最后写出 `.wxss` 文件（通过 `name: '[path][name].wxss'`）。
+
+## Taro 系列（taro-app / taro-vue3-app / taro-webpack-tailwindcss-v4）
+- **核心实现**：`demo/taro-app/node_modules/@tarojs/webpack5-runner/dist/webpack/MiniWebpackModule.js`
+- `getCSSLoaders`（行 101-157）定义基础栈：`MiniCssExtractPlugin.loader → css-loader → postcss-loader`，并在启用 CSS Modules 时换成带模块配置的 css-loader。
+- `addCSSLoader`（行 92-99）会克隆上述栈并在尾部追加预处理器：
+  - `scss`/`sass`：`… → resolve-url-loader → sass-loader`（行 34-42）。
+  - `less`：`… → less-loader`（行 43-46）。
+  - `stylus`：`… → stylus-loader`（行 47-50）。
+- 结果：任意样式都会先被对应的预处理器处理，再经过 PostCSS，最后交给 `MiniCssExtractPlugin` 输出 `.wxss`。
+
+## Mpx 系列（mpx-app / mpx-tailwindcss-v4）
+- **基础栈**：继承 Vue CLI（`demo/mpx-app/node_modules/@vue/cli-service/lib/config/css.js:99-194`）
+  - 默认顺序：`MiniCssExtractPlugin.loader`（或 `vue-style-loader`）`→ css-loader → (cssnano 可选) → postcss-loader → 预处理器`。
+- **Mpx 注入**：`demo/mpx-app/node_modules/@mpxjs/webpack-plugin/lib/index.js:1883-2042`
+  - `typeLoaderProcessInfo.styles` 定义了 `css-loader → @mpxjs/wxss/loader → @mpxjs/style-compiler` 的串联，并在 `injectStyleStripLoader` 里确保条件编译 loader 紧跟在 `stylus/sass/less/css/wxss` 之后。
+  - 对 `.mpx` 模块的样式来说，整体顺序为：`MiniCssExtractPlugin.loader → css-loader（被替换为 wxss-loader）→ @mpxjs/wxss/loader → @mpxjs/style-compiler → postcss-loader → 预处理器`。
+
+## Uni-app（uni-app / uni-app-webpack5 / uni-app-webpack-tailwindcss-v4）
+- **链路**：`demo/uni-app/node_modules/@dcloudio/vue-cli-plugin-uni/lib/chain-webpack.js:40-146`
+  - 每个 `cssLang` 的 `oneOf` 均执行 `css-loader → extract-css-loader（非 H5 平台）→ uniapp-preprocess → postcss-loader → 预处理器`。
+  - 若启用了缓存，则在 `css-loader` 之前自动插入 `cache-loader`；`uniapp-preprocess` 会在 `css-loader`、预处理器前后各执行一次条件编译。
+- H5 进一步在 `lib/h5/cssnano-options.js` 中为每种 `rule(oneOf)` 加上 `postcss-loader(cssnano)`，次序保持不变。
+
+## Rax 小程序示例（rax-app）
+- **配置来源**：`demo/rax-app/node_modules/.pnpm/node_modules/build-plugin-rax-app/lib/userConfig/atoms/inlineStyle.js`
+  - 该 demo 的 `build.json` 目标是 `wechat-miniprogram`，属于 `miniappStandardList`。
+  - 默认（`inlineStyle: false`）：`setCSSRule` 会走 `configPostCssLoader`，即 `MiniCssExtractPlugin.loader → postcss-loader → css-loader`，并在全局样式（`src/global.*`）上额外拉出一条「内联链路」。
+  - 若设置 `inlineStyle: { forceEnableCSS: true }`，`css-module` 规则走“抽离链路”，普通 `css` 则拆成 `global` rule（抽离）和余下 rule（`vue-style-loader`/`stylesheet-loader` Inline）。
+  - 当 `inlineStyle` 显式设为 true，则所有规则都切到 `postcss-loader → stylesheet-loader` 的内联栈。
+- 因此本 demo 默认构建顺序是：`MiniCssExtractPlugin.loader → postcss-loader → css-loader`（抽离） + `postcss-loader → stylesheet-loader`（global.* 内联）。
+
+## 说明
+- `uni-app-tailwindcss-v4` / `taro-app-vite` 等 Vite 工程不在本文范围。
+- 需要查看 loader 以外的 patch（例如 `UnifiedWebpackPluginV5` 注入的 runtime loader）时，可结合 `packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin`。

packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v4.ts

@@ -150,13 +150,18 @@ export class UnifiedWebpackPluginV4 implements IBaseWebpackPlugin {
         if (runtimeLoaderRewriteOptions && runtimeCssImportRewriteLoaderExists && cssImportRewriteLoaderOptions) {
           const rewriteEntry = createCssImportRewriteLoaderEntry()
           if (rewriteEntry) {
+            // 为了让 rewrite 在执行顺序上先于 postcss-loader，需要把它插到
+            // postcss-loader 的后方（数组索引更大，执行时更靠前）。
             // @ts-ignore
             loaderEntries.splice(idx + 1, 0, rewriteEntry)
           }
         }
         if (runtimeClassSetLoaderExists) {
+          const postcssIndex = loaderEntries.findIndex((entry: any) => entry?.loader?.includes?.('postcss-loader'))
+          const insertIndex = postcssIndex === -1 ? idx : postcssIndex
+          // 将 class-set 插在 postcss-loader 的当前位置（数组索引更小），这样在实际执行顺序里它会排在 postcss-loader 之后。
           // @ts-ignore
-          loaderEntries.splice(idx, 0, createRuntimeClassSetLoaderEntry())
+          loaderEntries.splice(insertIndex, 0, createRuntimeClassSetLoaderEntry())
         }
       })
     })

packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v5.ts

@@ -150,12 +150,15 @@ export class UnifiedWebpackPluginV5 implements IBaseWebpackPlugin {
         if (cssImportRewriteLoaderOptions && runtimeCssImportRewriteLoaderExists) {
           const rewriteLoaderEntry = createCssImportRewriteLoaderEntry()
           if (rewriteLoaderEntry) {
+            // 让 rewrite 处于 postcss-loader 之后（数组索引更大），这样执行时会排在 postcss-loader 之前。
             loaderEntries.splice(idx + 1, 0, rewriteLoaderEntry)
           }
         }
         if (runtimeClassSetLoaderExists) {
           const classSetLoaderEntry = createRuntimeClassSetLoaderEntry()
-          loaderEntries.splice(idx, 0, classSetLoaderEntry)
+          const postcssIndex = loaderEntries.findIndex(entry => entry?.loader?.includes?.('postcss-loader'))
+          const insertIndex = postcssIndex === -1 ? idx : postcssIndex
+          loaderEntries.splice(insertIndex, 0, classSetLoaderEntry)
         }
       })
 

packages/weapp-tailwindcss/src/bundlers/webpack/loaders/weapp-tw-css-import-rewrite-loader.ts

@@ -1,6 +1,7 @@
 // @ts-nocheck
 import type { Buffer } from 'node:buffer'
 import type webpack from 'webpack'
+import process from 'node:process'
 import loaderUtils from 'loader-utils'
 import { rewriteTailwindcssImportsInCode } from '@/bundlers/shared/css-imports'
 
@@ -44,6 +45,10 @@ const WeappTwCssImportRewriteLoader: webpack.LoaderDefinitionFunction<CssImportR
   this: webpack.LoaderContext<any>,
   source: string | Buffer,
 ) {
+  if (process.env.WEAPP_TW_LOADER_DEBUG) {
+    // eslint-disable-next-line no-console
+    console.log('[weapp-tw-css-import-rewrite-loader] executing for', this.resourcePath)
+  }
   const opt = loaderUtils.getOptions(this)
   return transformSource(source, opt)
 }

packages/weapp-tailwindcss/src/bundlers/webpack/loaders/weapp-tw-runtime-classset-loader.ts

@@ -1,6 +1,7 @@
 // @ts-nocheck
 import type { Buffer } from 'node:buffer'
 import type webpack from 'webpack'
+import process from 'node:process'
 import loaderUtils from 'loader-utils'
 
 interface RuntimeClassSetLoaderOptions {
@@ -11,6 +12,10 @@ const WeappTwRuntimeClassSetLoader: webpack.LoaderDefinitionFunction<RuntimeClas
   this: webpack.LoaderContext<any>,
   source: string | Buffer,
 ) {
+  if (process.env.WEAPP_TW_LOADER_DEBUG) {
+    // eslint-disable-next-line no-console
+    console.log('[weapp-tw-runtime-classset-loader] executing for', this.resourcePath)
+  }
   const opt = loaderUtils.getOptions(this)
   const maybePromise = opt?.getClassSet?.()
   if (maybePromise && typeof (maybePromise as PromiseLike<void>).then === 'function') {