feat(weapp-tailwindcss): auto detect v4 css sources across bundlers

sonofmagic · sonofmagic · commit 4d0eb013fdaa · 2026-05-13T11:40:58.000+08:00
diff --git a/.changeset/tailwind-v4-vite-auto-css-entries.md b/.changeset/tailwind-v4-vite-auto-css-entries.md
@@ -2,4 +2,4 @@
 "weapp-tailwindcss": patch
 ---
 
-支持 Vite 场景下自动识别 Tailwind CSS v4 入口 CSS，未显式传入 `cssEntries` 时会在 CSS transform 阶段捕获包含 Tailwind 根指令的样式内容，并通过 `tailwindcss-patch@9.3.3` 的 `cssSources` 刷新运行时 patcher；显式配置 `cssEntries` 或 `cssSources` 时仍保持用户配置优先。
+支持 Vite、Webpack 和 Gulp 场景下自动识别 Tailwind CSS v4 入口 CSS，未显式传入 `cssEntries` 时会捕获包含 Tailwind 根指令的样式内容，并通过 `tailwindcss-patch@9.3.3` 的 `cssSources` 刷新运行时 patcher；显式配置 `cssEntries` 或 `cssSources` 时仍保持用户配置优先。
diff --git a/apps/taro-webpack-tailwindcss-v4/config/index.ts b/apps/taro-webpack-tailwindcss-v4/config/index.ts
@@ -1,5 +1,4 @@
 import type { UserConfigExport } from '@tarojs/cli'
-import path from 'node:path'
 import process from 'node:process'
 import { defineConfig } from '@tarojs/cli'
 import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin'
@@ -80,12 +79,6 @@ export default defineConfig<'webpack5'>(async (merge, { command, mode }) => {
                   tailwindcss: {
                     // 显示声明用的是 tailwindcss v4
                     version: 4,
-                    v4: {
-                      cssEntries: [
-                        // app.css 的路径
-                        path.resolve(__dirname, '../src/app.css'),
-                      ],
-                    },
                   },
                 },
               ],
diff --git a/apps/vite-native/vite.config.ts b/apps/vite-native/vite.config.ts
@@ -1,4 +1,3 @@
-import path from 'node:path'
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
 import { defineConfig } from 'weapp-vite/config'
 
@@ -19,9 +18,6 @@ export default defineConfig({
     // @ts-ignore
     WeappTailwindcss({
       rem2rpx: true,
-      cssEntries: [
-        path.resolve(import.meta.dirname, './app.css'),
-      ],
     }),
   ],
   css: {
diff --git a/demo/mpx-tailwindcss-v4/mpx.config.js b/demo/mpx-tailwindcss-v4/mpx.config.js
@@ -48,9 +48,6 @@ module.exports = defineConfig({
       new UnifiedWebpackPluginV5({
         rem2rpx: true,
         appType: 'mpx',
-        cssEntries: [
-          path.resolve(__dirname, 'src/app.css')
-        ]
       })
     )
   },
diff --git a/demo/mpx-tailwindcss-v5/mpx.config.js b/demo/mpx-tailwindcss-v5/mpx.config.js
@@ -48,9 +48,6 @@ module.exports = defineConfig({
       new UnifiedWebpackPluginV5({
         rem2rpx: true,
         appType: 'mpx',
-        cssEntries: [
-          path.resolve(__dirname, 'src/app.css')
-        ]
       })
     )
   },
diff --git a/demo/taro-vite-tailwindcss-v4/config/index.ts b/demo/taro-vite-tailwindcss-v4/config/index.ts
@@ -3,7 +3,6 @@ import { defineConfig, type UserConfigExport } from '@tarojs/cli'
 import devConfig from './dev'
 import prodConfig from './prod'
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-import path from 'path'
 
 const generator = {
   styleOptions: {
@@ -57,10 +56,6 @@ export default defineConfig<'vite'>(async (merge, { command, mode }) => {
         WeappTailwindcss({
           rem2rpx: true,
           generator,
-          cssEntries:[
-            // 对应 src/app.css 中 @import "tailwindcss"; 的入口文件
-            path.resolve(__dirname, '../src/app.css')
-          ],
           // injectAdditionalCssVarScope: true,
         })
       ]
diff --git a/demo/taro-vite-tailwindcss-v5/config/index.ts b/demo/taro-vite-tailwindcss-v5/config/index.ts
@@ -3,7 +3,6 @@ import { defineConfig, type UserConfigExport } from '@tarojs/cli'
 import devConfig from './dev'
 import prodConfig from './prod'
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-import path from 'path'
 
 const generator = {
   styleOptions: {
@@ -57,10 +56,6 @@ export default defineConfig<'vite'>(async (merge, { command, mode }) => {
         WeappTailwindcss({
           rem2rpx: true,
           generator,
-          cssEntries:[
-            // 对应 src/app.css 中 @import "tailwindcss"; 的入口文件
-            path.resolve(__dirname, '../src/app.css')
-          ],
           // injectAdditionalCssVarScope: true,
         })
       ]
diff --git a/demo/taro-webpack-tailwindcss-v4/config/index.ts b/demo/taro-webpack-tailwindcss-v4/config/index.ts
@@ -3,7 +3,6 @@ import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin'
 import devConfig from './dev'
 import prodConfig from './prod'
 import { UnifiedWebpackPluginV5, UserDefinedOptions } from 'weapp-tailwindcss/webpack'
-import path from 'path'
 
 const generator = {
   styleOptions: {
@@ -81,9 +80,6 @@ export default defineConfig<'webpack5'>(async (merge, { command, mode }) => {
                 {
                   rem2rpx: true,
                   generator,
-                  cssEntries:[
-                    path.resolve(__dirname,'../src/app.css')
-                  ]
                   // before 2248
                   // after 309
                   // cssCalc: ['--nutui']
diff --git a/demo/uni-app-tailwindcss-v4/vite.config.ts b/demo/uni-app-tailwindcss-v4/vite.config.ts
@@ -1,6 +1,6 @@
 import { defineConfig } from "vite";
 import { createRequire } from "node:module";
-import path, { dirname } from "node:path";
+import { dirname } from "node:path";
 // dynamic require of is not supported
 // const uni = require("@dcloudio/vite-plugin-uni");
 import uni from "@dcloudio/vite-plugin-uni";
@@ -18,11 +18,6 @@ export default defineConfig(async () => {
       uni(),
       WeappTailwindcss({
         rem2rpx: true,
-        cssEntries: [
-          path.resolve(__dirname, "src/main.css"),
-          path.resolve(__dirname, "src/common.css"),
-          path.resolve(__dirname, "src/pages-order/index.css"),
-        ],
       }),
     ],
     resolve: {
diff --git a/demo/uni-app-tailwindcss-v5/vite.config.ts b/demo/uni-app-tailwindcss-v5/vite.config.ts
@@ -1,6 +1,6 @@
 import { defineConfig } from "vite";
 import { createRequire } from "node:module";
-import path, { dirname } from "node:path";
+import { dirname } from "node:path";
 // dynamic require of is not supported
 // const uni = require("@dcloudio/vite-plugin-uni");
 import uni from "@dcloudio/vite-plugin-uni";
@@ -18,11 +18,6 @@ export default defineConfig(async () => {
       uni(),
       WeappTailwindcss({
         rem2rpx: true,
-        cssEntries: [
-          path.resolve(__dirname, "src/main.css"),
-          path.resolve(__dirname, "src/common.css"),
-          path.resolve(__dirname, "src/pages-order/index.css"),
-        ],
       }),
     ],
     resolve: {
diff --git a/demo/uni-app-x-hbuilderx-tailwindcss4/vite.config.ts b/demo/uni-app-x-hbuilderx-tailwindcss4/vite.config.ts
@@ -1,4 +1,3 @@
-import path from 'node:path'
 // import uni from '@dcloudio/vite-plugin-uni'
 import { defineConfig } from 'vite'
 import { uniAppX } from 'weapp-tailwindcss/presets'
@@ -12,7 +11,6 @@ export default defineConfig({
       uniAppX({
         base: __dirname,
         rem2rpx: true,
-        cssEntries: [path.resolve(__dirname, 'main.css')],
       }),
     ),
     debugX({
diff --git a/demo/web/index.js b/demo/web/index.js
@@ -118,12 +118,21 @@ async function runVersion(version) {
 
   const ctx = createContext({
     tailwindcssBasedir: demoDir,
-    cssEntries: isV4 ? [cssEntryPath] : [],
     tailwindcss: {
       cwd: demoDir,
       config: tailwindConfigPath,
       packageName: isV4 ? 'tailwindcss4' : 'tailwindcss',
       version: isV4 ? 4 : 3,
+      v4: isV4
+        ? {
+            cssSources: [
+              {
+                file: cssEntryPath,
+                css,
+              },
+            ],
+          }
+        : undefined,
     },
   })
 
diff --git a/packages/weapp-tailwindcss/src/bundlers/gulp/index.ts b/packages/weapp-tailwindcss/src/bundlers/gulp/index.ts
@@ -5,11 +5,13 @@ import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
 import stream from 'node:stream'
+import { hasTailwindRootDirectives } from '@/bundlers/shared/generator-css/directives'
 import { getCompilerContext } from '@/context'
 import { createDebug } from '@/debug'
 import { shouldSkipJsTransform } from '@/js/precheck'
 import { createTailwindRuntimeReadyPromise, ensureRuntimeClassSet } from '@/tailwindcss/runtime'
 import { getRuntimeClassSetSignature } from '@/tailwindcss/runtime/cache'
+import { hasConfiguredTailwindV4CssRoots, upsertTailwindV4CssSource } from '@/tailwindcss/v4/css-sources'
 import { processCachedTask } from '../shared/cache'
 import { generateCssByGenerator } from '../shared/generator-css'
 
@@ -23,7 +25,11 @@ const Transform = stream.Transform
  * @link https://tw.icebreaker.top/docs/quick-start/frameworks/native
  */
 export function createPlugins(options: UserDefinedOptions = {}) {
-  const opts = getCompilerContext(options)
+  const hasInitialTailwindCssRoots = hasConfiguredTailwindV4CssRoots(options)
+  const opts = getCompilerContext({
+    ...options,
+    __internalDeferMissingCssEntriesWarning: true,
+  } as UserDefinedOptions)
 
   const { templateHandler, styleHandler, jsHandler, cache, twPatcher: initialTwPatcher, refreshTailwindcssPatcher } = opts
 
@@ -64,6 +70,26 @@ export function createPlugins(options: UserDefinedOptions = {}) {
       [...nextRuntimeSet].sort().join('\n'),
     ].join('\n\n'))
   }
+
+  async function registerAutoCssSource(file: File, rawSource: string) {
+    if (
+      hasInitialTailwindCssRoots
+      || (runtimeState.twPatcher.majorVersion ?? 0) < 4
+      || !file.path
+      || !hasTailwindRootDirectives(rawSource)
+    ) {
+      return
+    }
+    const changed = upsertTailwindV4CssSource(opts, {
+      file: path.resolve(file.path),
+      css: rawSource,
+    })
+    if (!changed) {
+      return
+    }
+    runtimeSetInitialized = false
+    debug('detected tailwindcss v4 css source from gulp css file: %s', file.path)
+  }
   function resolveWithExtensions(base: string): string | undefined {
     for (const ext of MODULE_EXTENSIONS) {
       const candidate = `${base}${ext}`
@@ -221,6 +247,7 @@ export function createPlugins(options: UserDefinedOptions = {}) {
         return
       }
       const rawSource = file.contents.toString()
+      await registerAutoCssSource(file, rawSource)
       const nextRuntimeSet = await refreshRuntimeSet(true)
       await processCachedTask<string>({
         cache,
diff --git a/packages/weapp-tailwindcss/src/bundlers/vite/index.ts b/packages/weapp-tailwindcss/src/bundlers/vite/index.ts
@@ -1,4 +1,3 @@
-import type { TailwindV4CssSource } from 'tailwindcss-patch'
 import type { Plugin, ResolvedConfig } from 'vite'
 import type { UserDefinedOptions } from '@/types'
 import path from 'node:path'
@@ -9,6 +8,7 @@ import { vitePluginName } from '@/constants'
 import { getCompilerContext } from '@/context'
 import { toCustomAttributesEntities } from '@/context/custom-attributes'
 import { createDebug } from '@/debug'
+import { hasConfiguredTailwindV4CssRoots, upsertTailwindV4CssSource } from '@/tailwindcss/v4/css-sources'
 import { createUniAppXPlugins } from '@/uni-app-x'
 import { isUniAppXEnabled } from '@/uni-app-x/options'
 import { resolveUniUtsPlatform } from '@/utils'
@@ -30,62 +30,6 @@ const debug = createDebug()
 const weappTailwindcssPackageDir = resolvePackageDir('weapp-tailwindcss')
 const weappTailwindcssDirPosix = slash(weappTailwindcssPackageDir)
 
-function hasCssEntriesValue(value: unknown) {
-  if (typeof value === 'string') {
-    return value.trim().length > 0
-  }
-  return Array.isArray(value) && value.some(entry => typeof entry === 'string' && entry.trim().length > 0)
-}
-
-function hasCssSourcesValue(value: unknown) {
-  return Array.isArray(value) && value.some((source) => {
-    return typeof source === 'object'
-      && source !== null
-      && typeof (source as { css?: unknown }).css === 'string'
-      && (source as { css: string }).css.trim().length > 0
-  })
-}
-
-function hasConfiguredTailwindCssRoots(options: UserDefinedOptions, opts: { cssEntries?: string[] }) {
-  return hasCssEntriesValue(opts.cssEntries)
-    || hasCssEntriesValue(options.cssEntries)
-    || hasCssEntriesValue(options.tailwindcss?.v4?.cssEntries)
-    || hasCssEntriesValue((options.tailwindcssPatcherOptions as any)?.tailwindcss?.v4?.cssEntries)
-    || hasCssSourcesValue(options.tailwindcss?.v4?.cssSources)
-    || hasCssSourcesValue((options.tailwindcssPatcherOptions as any)?.tailwindcss?.v4?.cssSources)
-}
-
-function normalizeCssSourceFile(file: string | undefined) {
-  if (!file) {
-    return undefined
-  }
-  return path.isAbsolute(file) ? path.normalize(file) : file
-}
-
-function upsertAutoCssSource(opts: UserDefinedOptions, source: TailwindV4CssSource) {
-  const tailwindcss = opts.tailwindcss ?? {}
-  const v4 = tailwindcss.v4 ?? {}
-  const cssSources = [...(v4.cssSources ?? [])]
-  const sourceFile = normalizeCssSourceFile(source.file)
-  const existingIndex = cssSources.findIndex(candidate => normalizeCssSourceFile(candidate.file) === sourceFile)
-  if (existingIndex >= 0) {
-    cssSources[existingIndex] = {
-      ...cssSources[existingIndex],
-      ...source,
-    }
-  }
-  else {
-    cssSources.push(source)
-  }
-  opts.tailwindcss = {
-    ...tailwindcss,
-    v4: {
-      ...v4,
-      cssSources,
-    },
-  }
-}
-
 /**
  * @name WeappTailwindcss
  * @description uni-app vite / uni-app-x 版本插件
@@ -117,7 +61,10 @@ export function WeappTailwindcss(options: UserDefinedOptions = {}): Plugin[] | u
   const tailwindcssMajorVersion = initialTwPatcher.majorVersion ?? 0
   const shouldOwnTailwindGeneration = !disabledOptions.plugin
   const shouldRewriteCssImports = tailwindcssMajorVersion >= 4
-  const hasInitialTailwindCssRoots = hasConfiguredTailwindCssRoots(options, opts)
+  const hasInitialTailwindCssRoots = hasConfiguredTailwindV4CssRoots({
+    ...options,
+    cssEntries: opts.cssEntries ?? options.cssEntries,
+  })
   const autoCssSourceContent = new Map<string, string>()
   let refreshRuntimeStateForAutoCssSources: ((force: boolean) => Promise<void>) | undefined
   let autoCssSourcesRefresh: Promise<void> | undefined
@@ -138,7 +85,7 @@ export function WeappTailwindcss(options: UserDefinedOptions = {}): Plugin[] | u
       return
     }
     autoCssSourceContent.set(sourceFile, css)
-    upsertAutoCssSource(opts, {
+    upsertTailwindV4CssSource(opts, {
       file: sourceFile,
       css,
     })
diff --git a/packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v5-loaders.ts b/packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v5-loaders.ts
@@ -1,3 +1,4 @@
+import type { TailwindV4CssSource } from 'tailwindcss-patch'
 import type { Compiler } from 'webpack'
 import type { AppType, InternalUserDefinedOptions } from '@/types'
 import fs from 'node:fs'
@@ -15,6 +16,7 @@ interface SetupWebpackV5LoadersOptions {
   weappTailwindcssPackageDir: string
   shouldRewriteCssImports: boolean
   runtimeLoaderPath?: string
+  registerAutoCssSource?: (source: TailwindV4CssSource) => Promise<void> | void
   getClassSetInLoader: () => Promise<void>
   getRuntimeWatchDependencies: () => {
     files: ReadonlySet<string>
@@ -31,6 +33,7 @@ export function setupWebpackV5Loaders(options: SetupWebpackV5LoadersOptions) {
     weappTailwindcssPackageDir,
     shouldRewriteCssImports,
     runtimeLoaderPath,
+    registerAutoCssSource,
     getClassSetInLoader,
     getRuntimeWatchDependencies,
     debug,
@@ -54,6 +57,7 @@ export function setupWebpackV5Loaders(options: SetupWebpackV5LoadersOptions) {
     ? {
         pkgDir: weappTailwindcssPackageDir,
         appType,
+        registerCssSource: registerAutoCssSource,
       }
     : undefined
   const classSetLoaderOptions = {
diff --git a/packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v5.ts b/packages/weapp-tailwindcss/src/bundlers/webpack/BaseUnifiedPlugin/v5.ts
diff --git a/packages/weapp-tailwindcss/src/bundlers/webpack/loaders/weapp-tw-css-import-rewrite-loader.ts b/packages/weapp-tailwindcss/src/bundlers/webpack/loaders/weapp-tw-css-import-rewrite-loader.ts
diff --git a/packages/weapp-tailwindcss/src/tailwindcss/v4/config.ts b/packages/weapp-tailwindcss/src/tailwindcss/v4/config.ts
diff --git a/packages/weapp-tailwindcss/src/tailwindcss/v4/css-sources.ts b/packages/weapp-tailwindcss/src/tailwindcss/v4/css-sources.ts
diff --git a/packages/weapp-tailwindcss/test/bundlers/css-imports.test.ts b/packages/weapp-tailwindcss/test/bundlers/css-imports.test.ts
diff --git a/packages/weapp-tailwindcss/test/bundlers/gulp.unit.test.ts b/packages/weapp-tailwindcss/test/bundlers/gulp.unit.test.ts
diff --git a/packages/weapp-tailwindcss/test/bundlers/webpack.v5.unit.test.ts b/packages/weapp-tailwindcss/test/bundlers/webpack.v5.unit.test.ts
