feat(vite): 拆分 Generic Web CSS-only 管线

Author: sonofmagic

.changeset/web-css-only.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": minor
+---
+
+将 `weapp-tailwindcss/vite/web` 拆分为真正的 Generic Web CSS-only 管线：默认只处理 CSS 生成与 HMR，不注册 JS/template、框架扩展、分包和小程序收尾；主入口识别为 Generic Web 后复用相同 profile，`styleInjector` 改为显式 opt-in。

README.md

@@ -43,7 +43,7 @@
 
 | 目标端 | 推荐入口 | 适用场景 |
 | --- | --- | --- |
-| Web / H5 | `weapp-tailwindcss/vite`、`/webpack`、`/rspack`、`/gulp` 或 Node API | 浏览器 CSS、H5 和普通 Web 构建 |
+| Web / H5 | `weapp-tailwindcss/vite/web`（CSS-only）或 `weapp-tailwindcss/vite`、`/webpack`、`/rspack`、`/gulp`、Node API | 浏览器 CSS、H5 和普通 Web 构建 |
 | 小程序 | 对应构建器入口，或 `@weapp-tailwindcss/cli --target weapp` | 微信、支付宝、抖音、QQ 等小程序 CSS |
 | App WebView | `weapp-tailwindcss` 的框架集成 | uni-app、Taro 等框架的 App WebView 构建 |
 | uni-app x | `weapp-tailwindcss/vite` | Android、iOS 与 HarmonyOS 原生应用构建 |
@@ -74,29 +74,23 @@ pnpm add -D tailwindcss weapp-tailwindcss
 
 ### 3. 注册构建器插件
 
-以 Vite 为例，先注册框架插件，再注册 `WeappTailwindcss`：
+以 Vite 为例，纯 Web 项目使用 CSS-only 入口：
 
 ```ts
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
-import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-
-const projectRoot = dirname(fileURLToPath(import.meta.url))
+import { WeappTailwindcssWeb } from 'weapp-tailwindcss/vite/web'
 
 export default defineConfig({
   plugins: [
-    // 先放你的框架插件，例如 uni()。
-    WeappTailwindcss({
-      cssEntries: [resolve(projectRoot, 'src/app.css')],
-      cssOptions: {
-        rem2rpx: true,
-      },
-    }),
+    WeappTailwindcssWeb(),
   ],
 })
 ```
 
+`vite/web` 只处理 Tailwind CSS 生成、CSS transform、CSS HMR 和 Web CSS 收尾，不注册 JS/template 转译、框架扩展、分包或小程序 finalizer。`styleInjector` 默认关闭，只有显式配置时才启用 Web 适配器。SSR、library mode、`optimizeDeps`、`cssMinify` 和 sourcemap 继续由 Vite 管理；CSS 入口必须实际 import 到 Vite 模块图中。
+
+需要同时支持小程序、框架扩展或多入口时，继续使用 `weapp-tailwindcss/vite` 主入口，并显式指定 `generator.target` 或 `platform`。无标记的 Generic Vite 项目会在 Vite 配置解析后自动复用 Web CSS-only profile。
+
 Webpack、Rspack、Gulp、Taro、uni-app、Mpx 和原生小程序的完整配置见[框架接入指南](https://tw.weapp.dev/zh-cn/docs/quick-start/frameworks/uni-app-vite)。
 
 ## CLI

README_en.md

@@ -43,7 +43,7 @@ The goal is simple: use one Tailwind input and generate the correct artifact for
 
 | Target | Recommended entry | Use it for |
 | --- | --- | --- |
-| Web / H5 | `weapp-tailwindcss/vite`, `/webpack`, `/rspack`, `/gulp`, or the Node API | Browser CSS, H5, and regular Web builds |
+| Web / H5 | `weapp-tailwindcss/vite/web` (CSS-only), `weapp-tailwindcss/vite`, `/webpack`, `/rspack`, `/gulp`, or the Node API | Browser CSS, H5, and regular Web builds |
 | Mini programs | The matching builder entry, or `@weapp-tailwindcss/cli --target weapp` | WeChat, Alipay, Douyin, QQ, and other mini-program CSS |
 | App WebView | `weapp-tailwindcss` framework integrations | App WebView builds from frameworks such as uni-app and Taro |
 | uni-app x | `weapp-tailwindcss/vite` | Native Android, iOS, and HarmonyOS application builds |
@@ -74,29 +74,23 @@ The entry must be imported by the project. `cssEntries` tells the generator whic
 
 ### 3. Register the builder integration
 
-With Vite, register the framework plugin first and `WeappTailwindcss` after it:
+For a pure Web project, use the CSS-only Vite entry:
 
 ```ts
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
-import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-
-const projectRoot = dirname(fileURLToPath(import.meta.url))
+import { WeappTailwindcssWeb } from 'weapp-tailwindcss/vite/web'
 
 export default defineConfig({
   plugins: [
-    // Put your framework plugin here first, for example uni().
-    WeappTailwindcss({
-      cssEntries: [resolve(projectRoot, 'src/app.css')],
-      cssOptions: {
-        rem2rpx: true,
-      },
-    }),
+    WeappTailwindcssWeb(),
   ],
 })
 ```
 
+`vite/web` only handles Tailwind CSS generation, CSS transforms, CSS HMR, and Web CSS finalization. It does not register JavaScript/template transforms, framework extensions, subpackage processing, or mini-program finalizers. The built-in `styleInjector` is disabled by default and is enabled only when explicitly configured. SSR, library mode, `optimizeDeps`, `cssMinify`, and sourcemaps remain Vite responsibilities; the CSS entry must be imported into Vite's module graph.
+
+When the same build also needs mini-program output, framework extensions, or multiple entries, use the main `weapp-tailwindcss/vite` entry and set `generator.target` or `platform` explicitly. An unmarked Generic Vite project automatically reuses the Web CSS-only profile after Vite resolves its configuration.
+
 See the [framework integration guides](https://tw.weapp.dev/docs/quick-start/frameworks/uni-app-vite) for Webpack, Rspack, Gulp, Taro, uni-app, Mpx, and native mini-program projects.
 
 ## CLI

packages/weapp-tailwindcss/src/bundlers/shared/v4-generation-core.ts

@@ -11,6 +11,8 @@ import { resolvePostcssRequestOption } from './generator-css/source-resolver/pos
 import { isVueScopedStyleRequest, stripRequestQuery } from './style-requests'
 
 export interface TailwindV4GenerationCoreInput extends GenerateCssByGeneratorOptions {
+  /** CSS-only 构建不需要 compiler graph/shadow artifact，固定使用 legacy 输出。 */
+  compilerMode?: 'legacy' | undefined
   compilationChanges?: CompilationDependencyChange[] | undefined
   frameworkPostcssOwner?: InternalUserDefinedOptions | undefined
   cssStage?: CssStage | undefined
@@ -180,7 +182,7 @@ async function generateTailwindV4CssWithImplementation(
 export async function generateTailwindV4Css(
   options: TailwindV4GenerationCoreInput,
 ): Promise<TailwindV4GenerationCoreResult | undefined> {
-  const mode = resolveCompilerMode()
+  const mode = options.compilerMode ?? resolveCompilerMode()
   const generationOptions = resolveGenerationOptions(options, mode)
   if (mode === 'legacy') {
     return generateTailwindV4CssWithImplementation(generationOptions, {

packages/weapp-tailwindcss/src/bundlers/vite/capability-profile.ts

@@ -4,6 +4,8 @@ import type { UserDefinedOptions } from '@/types'
 /** Vite 插件链按运行场景拆分的能力开关。 */
 export interface ViteCapabilityProfile {
   name: 'framework' | 'generic-web'
+  /** 是否只装配 CSS 生成链路，不注册 JS/template 和小程序产物处理。 */
+  cssOnly?: boolean
   frameworkName: ViteFrameworkName
   generatorTarget: 'web' | 'weapp' | 'app' | undefined
   platformFamily: 'web' | 'native-app' | 'mini-program' | 'unknown'
@@ -31,6 +33,7 @@ export const frameworkViteCapabilityProfile: ViteCapabilityProfile = {
 export function createGenericWebViteCapabilityProfile(options: UserDefinedOptions): ViteCapabilityProfile {
   return {
     name: 'generic-web',
+    cssOnly: true,
     frameworkName: 'generic',
     generatorTarget: 'web',
     platformFamily: 'web',

packages/weapp-tailwindcss/src/bundlers/vite/css-finalizer/generic-web-fast-path.ts

@@ -4,7 +4,7 @@ import type { CssFinalizerContext } from './options'
 import { stripBundlerGeneratedCssMarkers } from '../../shared/generated-css-marker'
 import { hasTailwindGeneratedCss, hasTailwindGeneratedCssMarkers } from '../../shared/generator-css'
 import { normalizeOutputPathKey } from '../../shared/module-graph'
-import { resolveViteCssPipelineOutputFile } from '../generate-bundle'
+import { resolveViteCssPipelineOutputFile } from '../css-output'
 import { collectMatchingGeneratedCssMarkerFiles, resolveViteProcessedCssAssetSource } from '../processed-css-assets/markers-imports'
 import { shouldUseGenericWebFinalizerFastPath } from '../shared/generic-web-production-fast-path'
 import { finalizeWebCss } from './options'

packages/weapp-tailwindcss/src/bundlers/vite/css-finalizer/web-plugin.ts

@@ -0,0 +1,74 @@
+import type { OutputBundle } from 'rollup'
+import type { Plugin } from 'vite'
+import type { CssFinalizerContext } from './options'
+import path from 'node:path'
+import process from 'node:process'
+import { disposeCompilerOwner, finalizeCompilerShadowRun } from '@/compiler'
+import { tryFinalizeGenericWebCss } from './generic-web-fast-path'
+
+/**
+ * Generic Web 专用 CSS finalizer。
+ *
+ * 该插件只处理已经在 CSS transform 阶段记录的 CSS asset，不扫描或改写
+ * HTML、JavaScript、模板和小程序分包产物。
+ */
+export function createViteWebCssFinalizerOutputPlugin(context: CssFinalizerContext): Plugin {
+  return {
+    name: 'weapp-tailwindcss:adaptor:web-css-finalizer',
+    enforce: 'post',
+    async closeBundle() {
+      if (context.getResolvedConfig()?.build?.watch != null) {
+        return
+      }
+      await disposeCompilerOwner(context.runtimeState)
+    },
+    async closeWatcher() {
+      await disposeCompilerOwner(context.runtimeState)
+    },
+    generateBundle: {
+      order: 'post',
+      async handler(_options, bundle: OutputBundle) {
+        const resolvedConfig = context.getResolvedConfig()
+        if (resolvedConfig?.command !== 'build') {
+          return
+        }
+        const rootDir = resolvedConfig.root ? path.resolve(resolvedConfig.root) : process.cwd()
+        const recordTiming = (phase: string, startedAt: number) => {
+          context.hmrTimingRecorder?.record(`webCssFinalizer.${phase}`, performance.now() - startedAt)
+        }
+        const startedAt = performance.now()
+        const finalized = tryFinalizeGenericWebCss({
+          bundle,
+          context,
+          createCssPipelineContext: file => ({
+            bundle,
+            currentGeneratorBranch: {
+              isWeb: true,
+              isNativeApp: false,
+              isMiniProgram: false,
+            },
+            currentGeneratorOptions: {
+              target: 'web',
+              enabled: true,
+            },
+            file,
+            opts: context.opts,
+            resolvedConfig,
+            resolveStylePlatform: () => 'web',
+          } as any),
+          isHarmonyAppStyleTarget: false,
+          isNativeAppStyleTarget: false,
+          isWebGeneratorTarget: true,
+          recordTiming,
+          rootDir,
+          sourceRoot: undefined,
+        })
+        if (!finalized) {
+          context.debug('Generic Web CSS finalizer skipped: no unique processed CSS asset')
+        }
+        finalizeCompilerShadowRun(context.runtimeState)
+        context.hmrTimingRecorder?.record('webCssFinalizer.total', performance.now() - startedAt)
+      },
+    },
+  }
+}

packages/weapp-tailwindcss/src/bundlers/vite/css-handler-options.ts

@@ -0,0 +1,104 @@
+import type { InternalUserDefinedOptions, IStyleHandlerOptions } from '@/types'
+import path from 'node:path'
+import { normalizeStyleHandlerMajorVersion } from '@/context/style-options'
+import { normalizeOutputPathKey } from '../shared/module-graph'
+import { stripRequestQuery } from '../shared/style-requests'
+
+type CssHandlerOptions = IStyleHandlerOptions & {
+  postcssOptions: {
+    options: {
+      from: string
+    }
+  }
+  majorVersion?: 4 | undefined
+  sourceOptions?: {
+    outputRoot?: string | undefined
+    requestFile?: string | undefined
+  } | undefined
+}
+
+interface CssHandlerOptionsCacheOptions {
+  getAppType: () => InternalUserDefinedOptions['appType']
+  mainCssChunkMatcher: InternalUserDefinedOptions['mainCssChunkMatcher']
+  getMajorVersion: () => number | undefined
+  getOutputRoot?: (() => string | undefined) | undefined
+  getExtraOptions?: ((file: string) => Partial<IStyleHandlerOptions>) | undefined
+  getDynamicCssOptions?: (() => Partial<IStyleHandlerOptions>) | undefined
+}
+
+export interface CssHandlerOptionsCache {
+  getCssHandlerOptions: (file: string) => CssHandlerOptions
+  getCssUserHandlerOptions: (file: string) => CssHandlerOptions
+}
+
+export function resolveViteCssHandlerExtraOptions(file: string) {
+  const normalized = normalizeOutputPathKey(file.replace(/[?#].*$/, ''))
+  return normalized.includes('/')
+    ? { isMainChunk: false }
+    : {}
+}
+
+export function createCssHandlerOptionsCache(options: CssHandlerOptionsCacheOptions): CssHandlerOptionsCache {
+  const cssHandlerOptionsCache = new Map<string, CssHandlerOptions>()
+  const cssUserHandlerOptionsCache = new Map<string, CssHandlerOptions>()
+
+  const getCssHandlerOptions = (file: string) => {
+    const majorVersion = options.getMajorVersion()
+    const appType = options.getAppType()
+    const isMainChunk = options.mainCssChunkMatcher(file, appType)
+    const outputRoot = options.getOutputRoot?.()
+    const sourceFile = stripRequestQuery(file)
+    const from = path.isAbsolute(sourceFile)
+      ? sourceFile
+      : outputRoot
+        ? path.resolve(outputRoot, sourceFile)
+        : sourceFile
+    const extraOptions = options.getExtraOptions?.(file) ?? {}
+    const dynamicCssOptions = options.getDynamicCssOptions?.() ?? {}
+    const cacheKey = `${majorVersion ?? 'unknown'}:${appType ?? 'unknown'}:${isMainChunk ? '1' : '0'}:${outputRoot ?? ''}:${file}:${JSON.stringify(extraOptions)}:${JSON.stringify(dynamicCssOptions)}`
+    const cached = cssHandlerOptionsCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const created = {
+      isMainChunk,
+      ...extraOptions,
+      ...dynamicCssOptions,
+      postcssOptions: {
+        options: {
+          from,
+        },
+      },
+      majorVersion: normalizeStyleHandlerMajorVersion(majorVersion),
+      sourceOptions: {
+        outputRoot,
+        ...(sourceFile === file ? {} : { requestFile: file }),
+      },
+    }
+    cssHandlerOptionsCache.set(cacheKey, created)
+    return created
+  }
+
+  const getCssUserHandlerOptions = (file: string) => {
+    const majorVersion = options.getMajorVersion()
+    const outputRoot = options.getOutputRoot?.()
+    const cacheKey = `${majorVersion ?? 'unknown'}:${outputRoot ?? ''}:${file}`
+    const cached = cssUserHandlerOptionsCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const created = {
+      ...getCssHandlerOptions(file),
+      isMainChunk: false,
+    }
+    cssUserHandlerOptionsCache.set(cacheKey, created)
+    return created
+  }
+
+  return {
+    getCssHandlerOptions,
+    getCssUserHandlerOptions,
+  }
+}

…dlers/vite/generate-bundle/css-output.ts …lwindcss/src/bundlers/vite/css-output.tspackages/weapp-tailwindcss/src/bundlers/vite/generate-bundle/css-output.ts renamed to packages/weapp-tailwindcss/src/bundlers/vite/css-output.ts packages/weapp-tailwindcss/src/bundlers/vite/generate-bundle/css-output.ts renamed to packages/weapp-tailwindcss/src/bundlers/vite/css-output.ts

@@ -2,8 +2,8 @@ import type { InternalUserDefinedOptions } from '@/types'
 import { existsSync, realpathSync } from 'node:fs'
 import path from 'node:path'
 import { postcss } from '@weapp-tailwindcss/postcss'
-import { normalizeOutputPathKey } from '../../shared/module-graph'
-import { isCSSRequest } from '../utils'
+import { normalizeOutputPathKey } from '../shared/module-graph'
+import { isCSSRequest } from './utils'
 
 export const SOURCE_STYLE_OUTPUT_EXT_RE = /\.(?:less|sass|scss|styl|stylus|pcss|postcss)$/i
 export const CSS_SOURCE_OUTPUT_EXT_RE = /\.(?:css|less|sass|scss|styl|stylus|pcss|postcss)$/i

packages/weapp-tailwindcss/src/bundlers/vite/frameworks/generic/web.ts

@@ -0,0 +1,59 @@
+import type { InternalUserDefinedOptions, UserDefinedOptions } from '@/types'
+import { createBuiltinViteWebStyleInjectorPlugins } from '@/style-injector/vite-web'
+import { createGenericWebViteCapabilityProfile } from '../../capability-profile'
+import { createCssOnlyVitePlugins } from '../../shared/create-css-only-plugins-runtime'
+import { createViteSourceOutputRelationOwner, withViteSourceOutputRelationOwner } from '../../source-output-relations'
+
+/** Generic Web CSS-only profile，供 `vite/web` 入口直接使用。 */
+export function createGenericWebVitePlugins(options: UserDefinedOptions | InternalUserDefinedOptions = {}) {
+  const capability = createGenericWebViteCapabilityProfile(options as UserDefinedOptions)
+  const owner = createViteSourceOutputRelationOwner()
+  const plugins = withViteSourceOutputRelationOwner(owner, () => createCssOnlyVitePlugins({
+    ...options,
+    __internalViteCapabilityProfile: capability,
+    __internalViteWebStyleInjectorFactory: createBuiltinViteWebStyleInjectorPlugins,
+  } as InternalUserDefinedOptions))
+  if (!plugins) {
+    owner.dispose()
+    return undefined
+  }
+  return plugins.map((plugin) => {
+    const wrapped: any = { ...plugin }
+    if (plugin.watchChange) {
+      const hook = plugin.watchChange
+      wrapped.watchChange = async function (this: unknown, ...args: any[]) {
+        const id = args[0]
+        const change = args[1]
+        if (change?.event === 'delete') {
+          owner.removeSource(id)
+        }
+        else if (typeof id === 'string') {
+          owner.observeSource(id)
+        }
+        return typeof hook === 'function' ? hook.apply(this, args) : hook.handler?.apply(this, args)
+      }
+    }
+    if (plugin.handleHotUpdate) {
+      const hook = plugin.handleHotUpdate
+      wrapped.handleHotUpdate = async function (this: unknown, ...args: any[]) {
+        const file = args[0]?.file
+        if (typeof file === 'string') {
+          owner.observeSource(file)
+        }
+        return typeof hook === 'function' ? hook.apply(this, args) : hook.handler?.apply(this, args)
+      }
+    }
+    if (plugin.closeBundle) {
+      const hook = plugin.closeBundle
+      wrapped.closeBundle = async function (this: unknown, ...args: any[]) {
+        try {
+          return typeof hook === 'function' ? await hook.apply(this, args) : await hook.handler?.apply(this, args)
+        }
+        finally {
+          owner.dispose()
+        }
+      }
+    }
+    return wrapped
+  })
+}