fix: optimize vite tailwind v4 hmr candidates

Author: sonofmagic

.changeset/fast-vite-source-candidates.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+优化 Vite watch 模式下 Tailwind v4 热更新性能：缓存 source candidates 扫描结果，优先按 `@source`/CSS 入口缩小扫描范围，并复用 Tailwind v4 generator 的增量结果，避免 demo 热更新时反复全量扫描源码和重复生成 CSS。

demo/gulp-tailwindcss-v4/src/app.css

@@ -1,3 +1,3 @@
 @import "tailwindcss";
-@config "../tailwind.config.js";
+@config "./tailwind.config.js";
 @source "./**/*.{html,js,ts,wxml,ttml}";

demo/gulp-tailwindcss-v4/src/sub-independent/pages/index.css

@@ -1,2 +1,2 @@
 @import "tailwindcss" source(none);
-@config "../../../tailwind.config.sub-independent.js";
+@config "./tailwind.config.sub-independent.js";

demo/gulp-tailwindcss-v4/src/sub-normal/pages/index.css

@@ -1,2 +1,2 @@
 @import "tailwindcss" source(none);
-@config "../../../tailwind.config.sub-normal.js";
+@config "./tailwind.config.sub-normal.js";

packages/weapp-tailwindcss/src/bundlers/shared/generator-css.ts

@@ -1,4 +1,6 @@
 import type { IStyleHandlerOptions } from '@weapp-tailwindcss/postcss/types'
+import type { GeneratorResolvedSource } from './generator-css/source-resolver'
+import type { TailwindSourceEntry } from '@/tailwindcss/source-scan'
 import type { InternalUserDefinedOptions } from '@/types'
 import postcss from 'postcss'
 import {
@@ -23,6 +25,8 @@ import {
   stripTailwindBanner,
 } from './generator-css/markers'
 import {
+
+  resolveGeneratorSourceEntries,
   resolveGeneratorSources,
 } from './generator-css/source-resolver'
 
@@ -65,6 +69,7 @@ export interface GenerateCssByGeneratorOptions {
   file: string
   cssHandlerOptions: IStyleHandlerOptions
   cssUserHandlerOptions: IStyleHandlerOptions
+  getSourceCandidatesForEntries?: ((entries: TailwindSourceEntry[] | undefined) => Set<string>) | undefined
   styleHandler: InternalUserDefinedOptions['styleHandler']
   debug: (format: string, ...args: unknown[]) => void
 }
@@ -83,6 +88,27 @@ function finalizeMiniProgramGeneratorCss(css: string, target: string) {
   return finalizeMiniProgramCss(css)
 }
 
+function mergeScopedRuntimeWithCurrentRuntime(
+  scopedRuntime: Set<string>,
+  runtime: Set<string>,
+  options: {
+    cssHandlerOptions: IStyleHandlerOptions
+    isolateCssSource: boolean
+  },
+) {
+  if (runtime.size === 0 || !options.cssHandlerOptions.isMainChunk || options.isolateCssSource) {
+    return scopedRuntime
+  }
+  return new Set([
+    ...scopedRuntime,
+    ...runtime,
+  ])
+}
+
+function shouldIsolateMatchedCssSource(source: GeneratorResolvedSource, sourceEntries: TailwindSourceEntry[] | undefined) {
+  return Boolean(source.__weappTailwindcssMeta?.matchedCssSourceFile && sourceEntries?.length)
+}
+
 function resolveGeneratorStyleOptions(
   opts: InternalUserDefinedOptions,
   cssHandlerOptions: IStyleHandlerOptions,
@@ -207,6 +233,7 @@ export async function generateCssByGenerator(
     file,
     cssHandlerOptions,
     cssUserHandlerOptions,
+    getSourceCandidatesForEntries,
     styleHandler,
     debug,
   } = options
@@ -269,10 +296,23 @@ export async function generateCssByGenerator(
     const configuredContainerCompat = hasConfiguredContainerCompatSources(sources)
     const generatedResults = await Promise.all(sources.map(async (source) => {
       const generator = createWeappTailwindcssGenerator(source)
+      const sourceEntries = getSourceCandidatesForEntries && majorVersion === 4
+        ? await resolveGeneratorSourceEntries(source, runtimeState)
+        : undefined
+      const scopedRuntime = sourceEntries
+        ? getSourceCandidatesForEntries?.(sourceEntries)
+        : undefined
+      const isolateCssSource = shouldIsolateMatchedCssSource(source, sourceEntries)
+      const sourceRuntime = scopedRuntime && (scopedRuntime.size > 0 || isolateCssSource)
+        ? mergeScopedRuntimeWithCurrentRuntime(scopedRuntime, runtime, {
+            cssHandlerOptions,
+            isolateCssSource,
+          })
+        : runtime
       return generator.generate({
-        candidates: runtime,
+        candidates: sourceRuntime,
         incrementalCache: majorVersion === 3 || majorVersion === 4,
-        scanSources: majorVersion === 4 && runtime.size === 0,
+        scanSources: majorVersion === 4 && sourceRuntime.size === 0 && !isolateCssSource,
         styleOptions: generatorStyleOptions,
         tailwindcssV3Compatibility: generatorOptions.tailwindcssV3Compatibility,
         target: generatorOptions.target,
@@ -370,6 +410,14 @@ export async function generateCssByGenerator(
     if (generated.target === 'weapp') {
       css = inheritLegacyUnitConvertedDeclarations(css, effectiveRawSource)
     }
+    if (sources.some(source => (source as GeneratorResolvedSource).__weappTailwindcssMeta?.matchedCssSourceFile)) {
+      return {
+        css: finalizeMiniProgramGeneratorCss(css, generated.target),
+        target: generated.target,
+        source: 'generator',
+        dependencies: generated.dependencies,
+      }
+    }
     css = await appendLegacyCompatCss(
       css,
       effectiveRawSource,

packages/weapp-tailwindcss/src/bundlers/shared/generator-css/source-resolver.ts

@@ -4,6 +4,7 @@ import type { InternalUserDefinedOptions } from '@/types'
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
+import { resolveTailwindV4EntriesFromCss } from '@/bundlers/vite/source-scan'
 import {
   resolveTailwindV3Source,
   resolveTailwindV3SourceFromPatcher,
@@ -33,11 +34,27 @@ interface GeneratorSourceRuntimeState {
   twPatcher: InternalUserDefinedOptions['twPatcher']
 }
 
+export interface GeneratorSourceMetadata {
+  matchedCssSourceFile?: string | undefined
+}
+
+export type GeneratorResolvedSource = TailwindResolvedSource & {
+  __weappTailwindcssMeta?: GeneratorSourceMetadata | undefined
+}
+
 function resolvePostcssFromOption(cssHandlerOptions: IStyleHandlerOptions) {
   const from = cssHandlerOptions.postcssOptions?.options?.from
   return typeof from === 'string' && from.length > 0 ? from : undefined
 }
 
+function resolvePostcssSourceFile(cssHandlerOptions: IStyleHandlerOptions) {
+  const from = resolvePostcssFromOption(cssHandlerOptions)
+  if (!from || !path.isAbsolute(from)) {
+    return undefined
+  }
+  return from.replace(/[?#].*$/, '')
+}
+
 export function resolveCssSourceBase(file: string, cssHandlerOptions: IStyleHandlerOptions) {
   const from = resolvePostcssFromOption(cssHandlerOptions)
   const baseFile = from ?? file
@@ -107,6 +124,41 @@ function getOutputFileStem(file: string) {
   return path.basename(normalized, path.extname(normalized))
 }
 
+function getOutputFileWithoutExtension(file: string) {
+  const normalized = file.replace(/[?#].*$/, '')
+  const ext = path.extname(normalized)
+  return ext ? normalized.slice(0, -ext.length) : normalized
+}
+
+function normalizeMatchPath(file: string) {
+  return file.split(path.sep).join('/')
+}
+
+function stripKnownBuildRootPrefix(file: string) {
+  const segments = normalizeMatchPath(file).split('/')
+  const knownRoots = new Set(['dist', 'src'])
+  for (let index = segments.length - 1; index >= 0; index--) {
+    if (knownRoots.has(segments[index]!)) {
+      return segments.slice(index + 1).join('/')
+    }
+  }
+  return segments.join('/')
+}
+
+function isMatchingTailwindV4CssSourceFile(file: string, cssSourceFile: string) {
+  const outputBase = normalizeMatchPath(getOutputFileWithoutExtension(path.resolve(file)))
+  const sourceBase = normalizeMatchPath(getOutputFileWithoutExtension(path.resolve(cssSourceFile)))
+  const outputRelativeBase = stripKnownBuildRootPrefix(outputBase)
+  const sourceRelativeBase = stripKnownBuildRootPrefix(sourceBase)
+  return outputBase === sourceBase
+    || outputBase.endsWith(`/${sourceBase}`)
+    || sourceBase.endsWith(`/${outputBase}`)
+    || (
+      outputRelativeBase.length > 0
+      && outputRelativeBase === sourceRelativeBase
+    )
+}
+
 function resolveMatchingTailwindV4CssEntry(
   rawSource: string,
   file: string,
@@ -143,6 +195,43 @@ function resolveMatchingTailwindV4CssEntry(
   })
 }
 
+async function resolveMatchingTailwindV4CssSource(
+  rawSource: string,
+  file: string,
+  cssHandlerOptions: IStyleHandlerOptions,
+  sourceOptions: ReturnType<typeof resolveTailwindV4SourceOptionsFromPatcher>,
+) {
+  const cssSources = sourceOptions.cssSources
+  if (!cssSources?.length) {
+    return undefined
+  }
+
+  const normalizedRawSource = normalizeCssSourceForCompare(rawSource)
+  const sourceFile = resolvePostcssSourceFile(cssHandlerOptions)
+  const matchingSource = cssSources.find((cssSource) => {
+    if (typeof cssSource.css !== 'string' || cssSource.css.length === 0) {
+      return false
+    }
+    if (sourceFile && typeof cssSource.file === 'string' && path.resolve(sourceFile) === path.resolve(cssSource.file)) {
+      return true
+    }
+    if (typeof cssSource.file === 'string' && isMatchingTailwindV4CssSourceFile(file, cssSource.file)) {
+      return true
+    }
+    return normalizeCssSourceForCompare(cssSource.css) === normalizedRawSource
+  })
+  if (!matchingSource) {
+    return undefined
+  }
+  const source = await resolveTailwindV4Source({
+    ...omitUndefined(sourceOptions),
+    cssSources: [matchingSource],
+  })
+  return withGeneratorSourceMetadata(source, {
+    matchedCssSourceFile: typeof matchingSource.file === 'string' ? matchingSource.file : undefined,
+  })
+}
+
 function tryResolveTailwindV4SourceOptions(
   runtimeState: GeneratorSourceRuntimeState,
 ) {
@@ -161,6 +250,32 @@ function hasConfiguredTailwindV4CssSource(
     || Boolean(sourceOptions?.cssSources?.length)
 }
 
+function createTailwindV4CssSourceResolver(
+  sourceOptions: ReturnType<typeof resolveTailwindV4SourceOptionsFromPatcher>,
+  generatorOptions: NormalizedWeappTailwindcssGeneratorOptions | undefined,
+) {
+  return (cssSource: NonNullable<typeof sourceOptions.cssSources>[number]) =>
+    resolveTailwindV4Source({
+      ...omitUndefined(sourceOptions),
+      cssSources: [cssSource],
+    }).then(source => generatorOptions?.config
+      ? {
+          ...source,
+          css: prependConfigDirective(source.css, generatorOptions.config),
+        }
+      : source)
+}
+
+function withGeneratorSourceMetadata(
+  source: TailwindResolvedSource,
+  metadata: GeneratorSourceMetadata,
+): GeneratorResolvedSource {
+  return {
+    ...source,
+    __weappTailwindcssMeta: metadata,
+  }
+}
+
 function createTailwindV4ApplyReferenceSource(css: string, sourceOptions: { packageName?: string }) {
   if (!hasTailwindApplyDirective(css) || hasTailwindRootDirectives(css)) {
     return css
@@ -211,10 +326,13 @@ export async function resolveGeneratorSource(
   }
 
   const sourceOptions = tryResolveTailwindV4SourceOptions(runtimeState)
+  const matchedCssSource = sourceOptions
+    ? await resolveMatchingTailwindV4CssSource(rawSource, file, cssHandlerOptions, sourceOptions)
+    : undefined
   const configuredCssSource = sourceOptions
     && hasConfiguredTailwindV4CssSource(sourceOptions)
     && hasTailwindGeneratedCssMarkers(rawSource)
-    ? await resolveTailwindV4Source(sourceOptions)
+    ? matchedCssSource ?? await resolveTailwindV4Source(sourceOptions)
     : undefined
   if (configuredCssSource) {
     return generatorOptions?.config
@@ -240,7 +358,7 @@ export async function resolveGeneratorSource(
         cssEntries: [sourceOptions.cssEntries[0]!],
       })
     : undefined
-  const preferredCssEntrySource = matchedCssEntrySource ?? mainCssEntrySource
+  const preferredCssEntrySource = matchedCssEntrySource ?? matchedCssSource ?? mainCssEntrySource
   if (preferredCssEntrySource) {
     return generatorOptions?.config
       ? {
@@ -310,13 +428,32 @@ export async function resolveGeneratorSources(
     ]
   }
 
+  const matchedCssEntrySource = cssEntrySource
+    ? await resolveMatchingTailwindV4CssEntry(rawSource, file, sourceOptions)
+    : undefined
+  const matchedCssSource = await resolveMatchingTailwindV4CssSource(rawSource, file, cssHandlerOptions, sourceOptions)
+  const preferredCssEntrySource = matchedCssEntrySource ?? matchedCssSource
+  if (preferredCssEntrySource) {
+    return [
+      generatorOptions?.config
+        ? {
+            ...preferredCssEntrySource,
+            css: prependConfigDirective(preferredCssEntrySource.css, generatorOptions.config),
+          }
+        : preferredCssEntrySource,
+    ]
+  }
+
   if (!sourceOptions.cssEntries || sourceOptions.cssEntries.length <= 1) {
+    if (sourceOptions.cssSources?.length) {
+      return Promise.all(sourceOptions.cssSources.map(createTailwindV4CssSourceResolver(sourceOptions, generatorOptions)))
+    }
     return [
       await resolveGeneratorSource(majorVersion, runtimeState, rawSource, file, cssHandlerOptions, generatorOptions),
     ]
   }
 
-  const sources = await Promise.all(sourceOptions.cssEntries.map(cssEntry =>
+  const cssEntrySources = await Promise.all(sourceOptions.cssEntries.map(cssEntry =>
     resolveTailwindV4Source({
       ...omitUndefined(sourceOptions),
       cssEntries: [cssEntry],
@@ -327,5 +464,65 @@ export async function resolveGeneratorSources(
         }
       : source),
   ))
-  return sources
+  const cssSources = sourceOptions.cssSources?.length
+    ? await Promise.all(sourceOptions.cssSources.map(createTailwindV4CssSourceResolver(sourceOptions, generatorOptions)))
+    : []
+  return [
+    ...cssEntrySources,
+    ...cssSources,
+  ]
+}
+
+export async function resolveGeneratorSourceEntries(source: TailwindResolvedSource, runtimeState?: GeneratorSourceRuntimeState) {
+  if (!('css' in source) || !('base' in source) || !('baseFallbacks' in source)) {
+    return undefined
+  }
+  const sourceMetadata = (source as GeneratorResolvedSource).__weappTailwindcssMeta
+  const resolved = await resolveTailwindV4EntriesFromCss(source.css, source.base)
+  if (resolved?.entries.length || (!resolved?.explicit && !sourceMetadata?.matchedCssSourceFile) || !runtimeState) {
+    return resolved?.entries
+  }
+  const sourceOptions = tryResolveTailwindV4SourceOptions(runtimeState)
+  const matchingCssSource = sourceOptions?.cssSources?.find((cssSource) => {
+    if (
+      sourceMetadata?.matchedCssSourceFile
+      && typeof cssSource.file === 'string'
+      && path.resolve(cssSource.file) === path.resolve(sourceMetadata.matchedCssSourceFile)
+    ) {
+      return true
+    }
+    return cssSource.css === source.css
+  })
+  if (!matchingCssSource) {
+    return resolved?.entries
+  }
+  const sourceResolved = await resolveTailwindV4EntriesFromCss(
+    matchingCssSource.css,
+    typeof matchingCssSource.base === 'string' && matchingCssSource.base.length > 0
+      ? matchingCssSource.base
+      : typeof matchingCssSource.file === 'string' && matchingCssSource.file.length > 0
+        ? path.dirname(matchingCssSource.file)
+        : source.base,
+  )
+  if (sourceResolved?.entries.length) {
+    return sourceResolved.entries
+  }
+  for (const dependency of matchingCssSource.dependencies ?? []) {
+    if (!existsSync(dependency)) {
+      continue
+    }
+    try {
+      const dependencyResolved = await resolveTailwindV4EntriesFromCss(
+        readFileSync(dependency, 'utf8'),
+        path.dirname(dependency),
+      )
+      if (dependencyResolved?.entries.length) {
+        return dependencyResolved.entries
+      }
+    }
+    catch {
+      // 依赖内容只用于裁剪候选，读取失败时回退到 Tailwind 自身生成逻辑。
+    }
+  }
+  return resolved.entries
 }