fix: cache tailwind v4 incremental css generation

sonofmagic · sonofmagic · commit 2eae0935d5c0 · 2026-05-18T11:35:40.000+08:00
diff --git a/.changeset/v4-incremental-generator-cache.md b/.changeset/v4-incremental-generator-cache.md
@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+优化 Tailwind CSS v4 在 Vite watch 下的热更新性能，避免已有候选集时重复扫描源码，并复用增量 CSS 生成缓存。
diff --git a/packages/weapp-tailwindcss/src/bundlers/shared/generator-css.ts b/packages/weapp-tailwindcss/src/bundlers/shared/generator-css.ts
@@ -271,8 +271,8 @@ export async function generateCssByGenerator(
       const generator = createWeappTailwindcssGenerator(source)
       return generator.generate({
         candidates: runtime,
-        incrementalCache: majorVersion === 3,
-        scanSources: majorVersion === 4,
+        incrementalCache: majorVersion === 3 || majorVersion === 4,
+        scanSources: majorVersion === 4 && runtime.size === 0,
         styleOptions: generatorStyleOptions,
         tailwindcssV3Compatibility: generatorOptions.tailwindcssV3Compatibility,
         target: generatorOptions.target,
diff --git a/packages/weapp-tailwindcss/src/tailwindcss/v4-engine/generator.ts b/packages/weapp-tailwindcss/src/tailwindcss/v4-engine/generator.ts
@@ -1,16 +1,41 @@
-import type { TailwindV4Engine, TailwindV4GenerateOptions, TailwindV4ResolvedSource } from './types'
+import type { IStyleHandlerOptions } from '@weapp-tailwindcss/postcss/types'
+import type {
+  TailwindV4Engine,
+  TailwindV4GenerateOptions,
+  TailwindV4GenerateTarget,
+  TailwindV4ResolvedSource,
+  TailwindV4SourcePattern,
+} from './types'
+import fs from 'node:fs'
 import path from 'node:path'
 import postcss from 'postcss'
 import { createTailwindV4Engine as createPatchTailwindV4Engine } from 'tailwindcss-patch'
 import { omitUndefined } from '@/utils/object'
 import { filterUnsupportedMiniProgramTailwindV4Candidates } from './candidates'
+import { loadTailwindV4DesignSystem } from './design-system'
 import { transformTailwindV4CssByTarget } from './miniprogram'
 import { applyTailwindV3CompatibilityCss } from './tailwind-v3-compatibility'
 import { createTailwindV4DefaultColorThemeCss } from './tailwind-v4-default-colors'
 
 type TailwindV4ScanSourcePatterns = Exclude<NonNullable<TailwindV4GenerateOptions['scanSources']>, boolean>
 type TailwindV4ResolvedScanSources = TailwindV4GenerateOptions['scanSources']
 
+const incrementalGenerateCache = new Map<string, TailwindV4IncrementalGenerateCacheEntry>()
+
+interface TailwindV4IncrementalGenerateCacheEntry {
+  seenCandidates: Set<string>
+  classSet: Set<string>
+  css: string
+  rawCss: string
+  dependencies: string[]
+  sources: TailwindV4SourcePattern[]
+  root: null | 'none' | {
+    base: string
+    pattern: string
+  }
+  target: TailwindV4GenerateTarget
+}
+
 function findLeadingImportInsertionIndex(css: string) {
   const importPattern = /(?:^|\n)\s*@import\b[^;]*;/g
   let insertionIndex = 0
@@ -31,6 +56,84 @@ function applyMiniProgramTailwindV4DefaultColorCss(css: string) {
   return `${css.slice(0, insertionIndex)}\n${themeCss}\n${css.slice(insertionIndex)}`
 }
 
+function collectCandidates(candidates: Iterable<string> | undefined) {
+  return new Set(candidates ?? [])
+}
+
+function createStableJson(value: unknown): string {
+  if (value === undefined) {
+    return 'undefined'
+  }
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(item => createStableJson(item)).join(',')}]`
+  }
+  return `{${Object.keys(value).sort().map((key) => {
+    const record = value as Record<string, unknown>
+    return `${JSON.stringify(key)}:${createStableJson(record[key])}`
+  }).join(',')}}`
+}
+
+function createDependencyFingerprint(files: string[]) {
+  return files.map((file) => {
+    try {
+      const stat = fs.statSync(file)
+      return `${file}:${stat.size}:${stat.mtimeMs}`
+    }
+    catch {
+      return `${file}:missing`
+    }
+  }).join('|')
+}
+
+function createIncrementalGenerateCacheKey(
+  source: TailwindV4ResolvedSource,
+  target: TailwindV4GenerateTarget,
+  styleOptions: Partial<IStyleHandlerOptions> | undefined,
+  tailwindcssV3Compatibility: boolean | undefined,
+) {
+  return [
+    source.projectRoot,
+    source.base,
+    createStableJson(source.baseFallbacks),
+    source.css,
+    createDependencyFingerprint(source.dependencies),
+    target,
+    createStableJson(styleOptions),
+    createStableJson(tailwindcssV3Compatibility),
+  ].join('\0')
+}
+
+function createCompatibleSource(
+  source: TailwindV4ResolvedSource,
+  target: TailwindV4GenerateTarget,
+  tailwindcssV3Compatibility: boolean | undefined,
+) {
+  const shouldApplyTailwindV3Compatibility = tailwindcssV3Compatibility ?? target === 'weapp'
+  const filteredSourceCss = target === 'weapp'
+    ? removeUnlayeredTailwindV4PreflightImports(source.css)
+    : source.css
+  const sourceCss = shouldApplyTailwindV3Compatibility
+    ? applyTailwindV3CompatibilityCss(filteredSourceCss)
+    : target === 'weapp'
+      ? applyMiniProgramTailwindV4DefaultColorCss(filteredSourceCss)
+      : filteredSourceCss
+  const compatibleSourceCss = removeUnsupportedThemeVendorKeyframes(sourceCss)
+  return compatibleSourceCss === source.css ? source : { ...source, css: compatibleSourceCss }
+}
+
+function resolveTargetCandidates(
+  candidates: Iterable<string> | undefined,
+  target: TailwindV4GenerateTarget,
+) {
+  const collected = collectCandidates(candidates)
+  return target === 'weapp'
+    ? filterUnsupportedMiniProgramTailwindV4Candidates(collected)
+    : collected
+}
+
 function parseImportSourceParam(params: string) {
   const match = /\bsource\(\s*(none|(['"])(.*?)\2)\s*\)/.exec(params)
   if (!match) {
@@ -226,32 +329,22 @@ function removeUnsupportedThemeVendorKeyframes(css: string) {
 }
 
 export function createTailwindV4Engine(source: TailwindV4ResolvedSource): TailwindV4Engine {
-  async function generate(options: TailwindV4GenerateOptions = {}) {
+  async function generateOnce(
+    generateSource: TailwindV4ResolvedSource,
+    options: TailwindV4GenerateOptions = {},
+  ) {
     const {
       scanSources = true,
       styleOptions,
       tailwindcssV3Compatibility,
       target = 'weapp',
       ...patchOptions
     } = options
-    const shouldApplyTailwindV3Compatibility = tailwindcssV3Compatibility ?? target === 'weapp'
-    const filteredSourceCss = target === 'weapp'
-      ? removeUnlayeredTailwindV4PreflightImports(source.css)
-      : source.css
-    const sourceCss = shouldApplyTailwindV3Compatibility
-      ? applyTailwindV3CompatibilityCss(filteredSourceCss)
-      : target === 'weapp'
-        ? applyMiniProgramTailwindV4DefaultColorCss(filteredSourceCss)
-        : filteredSourceCss
-    const compatibleSourceCss = removeUnsupportedThemeVendorKeyframes(sourceCss)
-    const candidates = target === 'weapp'
-      ? filterUnsupportedMiniProgramTailwindV4Candidates(patchOptions.candidates)
-      : patchOptions.candidates
-    const engine = createPatchTailwindV4Engine(
-      compatibleSourceCss === source.css ? source : { ...source, css: compatibleSourceCss },
-    )
+    const compatibleSource = createCompatibleSource(generateSource, target, tailwindcssV3Compatibility)
+    const candidates = resolveTargetCandidates(patchOptions.candidates, target)
+    const engine = createPatchTailwindV4Engine(compatibleSource)
     const result = await engine.generate(omitUndefined({
-      scanSources: resolveScanSources(source, scanSources),
+      scanSources: resolveScanSources(compatibleSource, scanSources),
       ...patchOptions,
       candidates,
     }))
@@ -266,6 +359,93 @@ export function createTailwindV4Engine(source: TailwindV4ResolvedSource): Tailwi
     }
   }
 
+  async function generateWithIncrementalCache(options: TailwindV4GenerateOptions = {}) {
+    if ((options.sources?.length ?? 0) > 0 || options.bareArbitraryValues !== undefined || options.scanSources === true || Array.isArray(options.scanSources)) {
+      return generateOnce(source, options)
+    }
+
+    const target = options.target ?? 'weapp'
+    const compatibleSource = createCompatibleSource(source, target, options.tailwindcssV3Compatibility)
+    const requestedCandidates = resolveTargetCandidates(options.candidates, target)
+    const cacheKey = createIncrementalGenerateCacheKey(
+      compatibleSource,
+      target,
+      options.styleOptions,
+      options.tailwindcssV3Compatibility,
+    )
+    const cached = incrementalGenerateCache.get(cacheKey)
+    if (cached) {
+      const missingCandidates = [...requestedCandidates].filter(candidate => !cached.seenCandidates.has(candidate))
+      if (missingCandidates.length === 0) {
+        return {
+          css: cached.css,
+          rawCss: cached.rawCss,
+          classSet: new Set(cached.classSet),
+          rawCandidates: new Set(cached.seenCandidates),
+          dependencies: cached.dependencies,
+          sources: cached.sources,
+          root: cached.root,
+          target: cached.target,
+        }
+      }
+
+      const designSystem = await loadTailwindV4DesignSystem(compatibleSource)
+      const cssByCandidate = designSystem.candidatesToCss(missingCandidates)
+      const rawCssParts: string[] = []
+      const classSet = new Set<string>()
+      for (let index = 0; index < missingCandidates.length; index += 1) {
+        const candidate = missingCandidates[index]
+        const css = cssByCandidate[index]
+        if (candidate && typeof css === 'string' && css.trim().length > 0) {
+          rawCssParts.push(css)
+          classSet.add(candidate)
+        }
+      }
+      const rawCss = rawCssParts.join('\n')
+      const css = rawCss.length > 0
+        ? await transformTailwindV4CssByTarget(rawCss, target, options.styleOptions)
+        : ''
+
+      for (const candidate of missingCandidates) {
+        cached.seenCandidates.add(candidate)
+      }
+      for (const className of classSet) {
+        cached.classSet.add(className)
+      }
+      cached.css = [cached.css, css].filter(Boolean).join('\n')
+      cached.rawCss = [cached.rawCss, rawCss].filter(Boolean).join('\n')
+      return {
+        css: cached.css,
+        rawCss: cached.rawCss,
+        classSet: new Set(cached.classSet),
+        rawCandidates: new Set(cached.seenCandidates),
+        dependencies: cached.dependencies,
+        sources: cached.sources,
+        root: cached.root,
+        target: cached.target,
+      }
+    }
+
+    const generated = await generateOnce(source, options)
+    incrementalGenerateCache.set(cacheKey, {
+      seenCandidates: new Set(requestedCandidates),
+      classSet: new Set(generated.classSet),
+      css: generated.css,
+      rawCss: generated.rawCss,
+      dependencies: generated.dependencies,
+      sources: generated.sources,
+      root: generated.root,
+      target: generated.target,
+    })
+    return generated
+  }
+
+  async function generate(options: TailwindV4GenerateOptions = {}) {
+    return options.incrementalCache
+      ? generateWithIncrementalCache(options)
+      : generateOnce(source, options)
+  }
+
   return {
     source,
     loadDesignSystem: createPatchTailwindV4Engine(source).loadDesignSystem,
diff --git a/packages/weapp-tailwindcss/src/tailwindcss/v4-engine/types.ts b/packages/weapp-tailwindcss/src/tailwindcss/v4-engine/types.ts
@@ -14,6 +14,7 @@ export type TailwindV4GenerateTarget = 'weapp' | 'web' | 'tailwind'
 type TailwindV4PatchGenerateOptions = Omit<PatchTailwindV4GenerateOptions, 'target' | 'styleOptions' | 'tailwindcssV3Compatibility' | 'scanSources'>
 
 export interface TailwindV4GenerateOptions extends TailwindV4PatchGenerateOptions {
+  incrementalCache?: boolean | undefined
   target?: TailwindV4GenerateTarget | undefined
   styleOptions?: Partial<IStyleHandlerOptions> | undefined
   tailwindcssV3Compatibility?: boolean | undefined
diff --git a/packages/weapp-tailwindcss/test/tailwindcss/v4-engine.test.ts b/packages/weapp-tailwindcss/test/tailwindcss/v4-engine.test.ts
@@ -77,6 +77,39 @@ describe('tailwindcss v4 engine', () => {
     expect(transformed).not.toContain('color: 55rpx')
   })
 
+  it('can append new utilities via the v4 incremental cache without full source scans', async () => {
+    const source = await resolveTailwindV4Source({
+      css: MINIMAL_THEME_CSS,
+      base: process.cwd(),
+    })
+    const engine = createTailwindV4Engine(source)
+
+    const first = await engine.generate({
+      candidates: ['text-[88rpx]'],
+      incrementalCache: true,
+      scanSources: false,
+      styleOptions: {
+        isMainChunk: false,
+      },
+    })
+    const second = await engine.generate({
+      candidates: ['text-[88rpx]', 'text-[188rpx]'],
+      incrementalCache: true,
+      scanSources: false,
+      styleOptions: {
+        isMainChunk: false,
+      },
+    })
+
+    expect(first.classSet).toEqual(new Set(['text-[88rpx]']))
+    expect(second.classSet).toEqual(new Set(['text-[88rpx]', 'text-[188rpx]']))
+    expect(second.css).toContain('.text-_b88rpx_B')
+    expect(second.css).toContain('font-size: 88rpx')
+    expect(second.css).toContain('.text-_b188rpx_B')
+    expect(second.css).toContain('font-size: 188rpx')
+    expect(second.css.match(/\.text-_b88rpx_B/g) ?? []).toHaveLength(1)
+  })
+
   it('uses mini-program-safe Tailwind v4 default color variables for native v4 weapp output', async () => {
     const source = await resolveTailwindV4Source({
       css: `

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"weapp-tailwindcss": patch
 +---
++
 +优化 Tailwind CSS v4 在 Vite watch 下的热更新性能，避免已有候选集时重复扫描源码，并复用增量 CSS 生成缓存。