fix(uni-app-x): 修复 important utility 跨端编译

Refs #1113

Author: sonofmagic

.changeset/clever-issues-1113.md

@@ -0,0 +1,6 @@
+---
+"weapp-tailwindcss": patch
+"@weapp-tailwindcss/postcss": patch
+---
+
+修复 uni-app x 中 important utility 与局部 Sass `@apply` 在 Web、Android Vapor 等目标间编译不一致的问题。

packages/postcss/package.json

@@ -94,6 +94,7 @@
     "postcss-pxtrans": "^1.0.4",
     "postcss-rem-to-responsive-pixel": "catalog:postcssRem",
     "postcss-rule-unit-converter": "^0.2.3",
+    "postcss-scss": "^4.0.9",
     "postcss-selector-parser": "catalog:buildUtilities",
     "postcss-value-parser": "^4.2.0",
     "tailwindcss-config": "workspace:*"

packages/postcss/src/compat/uni-app-x.ts

@@ -2,7 +2,12 @@
 import type { Result as PostcssResult, Rule } from 'postcss'
 import type { Node, Pseudo } from 'postcss-selector-parser'
 import type { IStyleHandlerOptions } from '../types'
+import { splitCandidateTokens } from '@tailwindcss-mangle/engine'
 import postcss from 'postcss'
+import scssSyntax from 'postcss-scss'
+
+/** native Sass 可解析、PostCSS 阶段再还原的 important utility 标记。 */
+export const UNI_APP_X_IMPORTANT_APPLY_MARKER = '__weapp_tw_important__'
 
 const UNI_APP_X_BASE_CARRIER_SELECTORS = new Set([
   '*',
@@ -18,6 +23,72 @@ const REQUIRED_TW_VAR_RE = /var\(\s*(--tw-[\w-]+)\s*\)/g
 const CLASS_SELECTOR_RE = /\.[\w-]+/
 const SELECTOR_WHITESPACE_RE = /\s+/g
 
+function rewriteImportantApplyUtility(utility: string, marker: string) {
+  if (utility.startsWith('!') && !utility.startsWith('\\!')) {
+    return `${utility.slice(1)}${marker}`
+  }
+  if (utility.endsWith('!') && !utility.endsWith('\\!')) {
+    return `${utility.slice(0, -1)}${marker}`
+  }
+  return utility
+}
+
+function rewriteApplyParams(params: string, marker: string) {
+  const candidates = splitCandidateTokens(params)
+  if (candidates.length === 0) {
+    return params
+  }
+  let result = params
+  for (const candidate of candidates) {
+    const rewritten = rewriteImportantApplyUtility(candidate, marker)
+    if (rewritten !== candidate) {
+      result = result.replace(candidate, rewritten)
+    }
+  }
+  return result
+}
+
+/** 将 Sass 不可直接解析的 important utility 改写成跨预处理器中间形式。 */
+export function normalizeUniAppXImportantApplyForSass(css: string) {
+  try {
+    const root = postcss.parse(css, { from: undefined, syntax: scssSyntax })
+    let changed = false
+    root.walkAtRules('apply', (rule) => {
+      const params = rewriteApplyParams(rule.params, UNI_APP_X_IMPORTANT_APPLY_MARKER)
+      if (params !== rule.params) {
+        rule.params = params
+        changed = true
+      }
+    })
+    return changed ? root.toString() : css
+  }
+  catch {
+    return css
+  }
+}
+
+/** 在 Tailwind/PostCSS 处理前还原 native important utility 标记。 */
+export function restoreUniAppXImportantApplyMarker(css: string) {
+  if (!css.includes(UNI_APP_X_IMPORTANT_APPLY_MARKER)) {
+    return css
+  }
+  try {
+    const root = postcss.parse(css)
+    let changed = false
+    root.walkAtRules('apply', (rule) => {
+      if (!rule.params.includes(UNI_APP_X_IMPORTANT_APPLY_MARKER)) {
+        return
+      }
+      rule.params = rule.params.split(UNI_APP_X_IMPORTANT_APPLY_MARKER).join('!')
+      changed = true
+    })
+    return changed ? root.toString() : css
+  }
+  catch {
+    return css
+  }
+}
+
 interface TwDefaultDeclaration {
   prop: string
   value: string

packages/postcss/src/index.ts

@@ -44,6 +44,11 @@ export {
   type TailwindcssRpxToRemOptions,
 } from './compat/tailwindcss-rpx'
 export { normalizeTailwindcssV4InfinityCalcCss } from './compat/tailwindcss-v4'
+export {
+  normalizeUniAppXImportantApplyForSass,
+  restoreUniAppXImportantApplyMarker,
+  UNI_APP_X_IMPORTANT_APPLY_MARKER,
+} from './compat/uni-app-x'
 export {
   type NormalizedWebCssCompatOptions,
   normalizeWebCssCompatOptions,

packages/postcss/test/uni-app-x.test.ts

@@ -1,11 +1,20 @@
 import fs from 'fs-extra'
 import path from 'pathe'
+import { normalizeUniAppXImportantApplyForSass, restoreUniAppXImportantApplyMarker } from '@/compat/uni-app-x'
 import { applyUniAppXUvueCompatibility } from '@/compat/uni-app-x-uvue'
 import { createStyleHandler, postcss } from '@/index'
 
 const INVALID_UNI_APP_X_BASE_SELECTOR_RE = /(^|,)\s*(?:\*|view|text|::before|::after|:before|:after|::backdrop)\s*(?=,|\{)/m
 
 describe('uni-app-x', () => {
+  it('round-trips important apply utilities across Sass and PostCSS', () => {
+    const source = '.probe { @apply !mt-6 mt-6! text-sm; }'
+    const sassSafe = normalizeUniAppXImportantApplyForSass(source)
+
+    expect(sassSafe).toContain('@apply mt-6__weapp_tw_important__ mt-6__weapp_tw_important__ text-sm;')
+    expect(restoreUniAppXImportantApplyMarker(sassSafe)).toContain('@apply mt-6! mt-6! text-sm;')
+  })
+
   it('accepts Web local important apply syntax', async () => {
     const styleHandler = createStyleHandler({
       appType: 'uni-app-x',

packages/weapp-tailwindcss/src/uni-app-x/component-local-style.ts

@@ -1,6 +1,7 @@
 import type { NodePath } from '@babel/traverse'
 import type { StringLiteral, TemplateElement } from '@babel/types'
 import { splitCandidateTokens } from '@tailwindcss-mangle/engine'
+import { UNI_APP_X_IMPORTANT_APPLY_MARKER } from '@weapp-tailwindcss/postcss'
 import MagicString from 'magic-string'
 import { analyzeSource, babelParse } from '@/js/babel'
 import { isClassContextLiteralPath } from '@/js/class-context'
@@ -46,8 +47,12 @@ function createAlias(fileId: string, utility: string, index: number) {
   return `wtu-${createStableHash(`${fileId}:${utility}`)}-${index.toString(36)}`
 }
 
-function serializeApplyUtility(utility: string, options: { web?: boolean } = {}) {
-  const importantSuffix = options.web ? '!' : '#{\'!\'}'
+function serializeApplyUtility(utility: string, options: { native?: boolean, web?: boolean } = {}) {
+  const importantSuffix = options.native
+    ? UNI_APP_X_IMPORTANT_APPLY_MARKER
+    : options.web
+      ? '!'
+      : '#{\'!\'}'
   if (utility.startsWith('!') && !utility.startsWith('\\!')) {
     return `${utility.slice(1)}${importantSuffix}`
   }
@@ -283,14 +288,14 @@ export class UniAppXComponentLocalStyleCollector {
     return this.aliasByUtility.size > 0
   }
 
-  toStyleBlock(options: { web?: boolean } = {}) {
+  toStyleBlock(options: { native?: boolean, web?: boolean } = {}) {
     if (!this.hasStyles()) {
       return ''
     }
     return `<style scoped>\n${this.toStyleRules(options)}</style>\n`
   }
 
-  toStyleRules(options: { web?: boolean } = {}) {
+  toStyleRules(options: { native?: boolean, web?: boolean } = {}) {
     if (!this.hasStyles()) {
       return ''
     }

packages/weapp-tailwindcss/src/uni-app-x/transform.ts

@@ -3,6 +3,7 @@ import type { SourceMapInput } from 'rollup'
 import type { TransformResult } from 'vite'
 import type { CreateJsHandlerOptions, ICustomAttributesEntities, JsHandler } from '@/types'
 import { NodeTypes, parse as parseTemplate } from '@vue/compiler-dom'
+import { normalizeUniAppXImportantApplyForSass } from '@weapp-tailwindcss/postcss'
 import MagicString from 'magic-string'
 import { generateCode, replaceWxml } from '@/wxml'
 import { createAttributeMatcher } from '@/wxml/custom-attributes'
@@ -130,6 +131,7 @@ interface TransformUVueOptions {
   enableComponentLocalStyle?: boolean
   enablePageLocalStyle?: boolean
   pageMatcher?: (id: string) => boolean
+  native?: boolean
   webCustomAttributeDeep?: boolean
   onWebLocalStyleRules?: (rules: string) => void
 }
@@ -273,6 +275,14 @@ export function transformUVue(
   const matchCustomAttribute = createAttributeMatcher(customAttributesEntities)
   const ms = new MagicString(code)
   const descriptor = parseSfc(code)
+  if (options.native || options.onWebLocalStyleRules) {
+    for (const style of descriptor.styles) {
+      const normalized = normalizeUniAppXImportantApplyForSass(style.content)
+      if (normalized !== style.content) {
+        ms.update(style.start, style.end, normalized)
+      }
+    }
+  }
   const localStyleCollector = shouldEnableLocalStyle(id, options)
     ? new UniAppXComponentLocalStyleCollector(id, runtimeSet)
     : undefined
@@ -372,10 +382,14 @@ export function transformUVue(
       }
       else if (scopedStyle) {
         const separator = scopedStyle.content.endsWith('\n') ? '' : '\n'
-        ms.appendLeft(scopedStyle.end, `${separator}${localStyleCollector.toStyleRules()}`)
+        ms.appendLeft(scopedStyle.end, `${separator}${localStyleCollector.toStyleRules({ native: options.native })}`)
       }
       else {
-        ms.append(`\n${localStyleCollector.toStyleBlock({ web: Boolean(options.onWebLocalStyleRules) })}`)
+        // 新增的局部样式块会单独进入预处理器，important utility 统一使用中间标记。
+        ms.append(`\n${localStyleCollector.toStyleBlock({
+          native: options.native || Boolean(options.onWebLocalStyleRules),
+          web: Boolean(options.onWebLocalStyleRules),
+        })}`)
       }
     }
   }

packages/weapp-tailwindcss/src/uni-app-x/vite.ts

@@ -11,9 +11,14 @@ import type {
 } from '@/types'
 import path from 'node:path'
 import process from 'node:process'
+import {
+  normalizeUniAppXImportantApplyForSass,
+  restoreUniAppXImportantApplyMarker,
+} from '@weapp-tailwindcss/postcss'
 import { processCachedTask } from '@/bundlers/shared/cache'
 import { hasTailwindApplyDirective, hasTailwindRootDirectives } from '@/bundlers/shared/generator-css/directives'
 import { toAbsoluteOutputPath } from '@/bundlers/shared/module-graph'
+import { extractSfcStyleBlocks } from '@/bundlers/vite/generate-bundle/sfc-style-source'
 import { parseVueRequest } from '@/bundlers/vite/query'
 import { cleanUrl, formatPostcssSourceMap, isCSSRequest, normalizePath } from '@/bundlers/vite/utils'
 import { logger } from '@/logger'
@@ -46,6 +51,9 @@ function loadTransformUVue(): Promise<TransformUVue> {
 }
 const UVUE_NVUE_QUERY_RE = /\.(?:uvue|nvue)(?:\?.*)?$/
 const UVUE_NVUE_RE = /\.(?:uvue|nvue)$/
+function hasUniAppXImportantApply(source: string) {
+  return extractSfcStyleBlocks(source).some(style => normalizeUniAppXImportantApplyForSass(style.source) !== style.source)
+}
 function resolveUniAppXJsTransformEnabled(uniAppX: InternalUserDefinedOptions['uniAppX'] | undefined) {
   return uniAppX === undefined ? true : isUniAppXEnabled(uniAppX)
 }
@@ -92,6 +100,7 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
     }
   }>()
   const nativeLocalStyleModuleIds = new Set<string>()
+  const knownSfcSources = new Map<string, string>()
   const webLocalStyle = createUniAppXWebLocalStyleBridge(isWebGeneratorTarget)
   let componentLocalStyleEnabled: boolean | undefined
   const isNativeAppBuildTarget = createUniAppXNativeBuildTargetResolver(getResolvedConfig)
@@ -169,7 +178,10 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
       if (isCssModuleExport(code)) {
         return
       }
-      const sourceCode = normalizeRelativeTailwindReferences(code, id)
+      const sourceCode = normalizeRelativeTailwindReferences(
+        restoreUniAppXImportantApplyMarker(code),
+        id,
+      )
       const hasTailwindRoot = hasTailwindRootDirectives(sourceCode, { importFallback: true })
       const hasTailwindApply = hasTailwindApplyDirective(sourceCode)
       const shouldGenerateCss = hasTailwindRoot || hasTailwindApply
@@ -230,21 +242,45 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
   const cssPrePlugin: Plugin = {
     name: 'weapp-tailwindcss:uni-app-x:css:pre',
     enforce: 'pre',
-    async transform(code, id) {
-      if (!isEnabled()) {
-        return
-      }
-      await runtimeState.readyPromise
-      const { query } = parseVueRequest(id)
-      const styleCode = query.vue && query.type === 'style' ? webLocalStyle.appendToStyle(code, id) : code
-      const preprocessor = resolvePreprocessorTransform(styleCode, id, query.lang, {
-        isIosPlatform,
-        isNativeAppStyleTarget: isNativeAppStyleTarget(),
-      })
-      if (preprocessor) {
-        return preprocessor.result ?? (styleCode !== code ? { code: styleCode, map: null } : undefined)
-      }
-      return transformStyle(styleCode, id, query, this)
+    load: {
+      order: 'pre',
+      async handler(id) {
+        const { filename, query } = parseVueRequest(id)
+        if (!query.vue || query.type !== 'style' || !UVUE_NVUE_RE.test(filename)) {
+          return
+        }
+        const source = knownSfcSources.get(filename)
+        const style = source ? extractSfcStyleBlocks(source)[query.index ?? 0] : undefined
+        if (!style) {
+          return
+        }
+        const normalized = normalizeUniAppXImportantApplyForSass(style.source)
+        return normalized === style.source ? undefined : { code: normalized, map: null }
+      },
+    },
+    transform: {
+      order: 'pre',
+      async handler(code, id) {
+        if (!isEnabled()) {
+          return
+        }
+        await runtimeState.readyPromise
+        const { query } = parseVueRequest(id)
+        const styleCode = query.vue && query.type === 'style' ? webLocalStyle.appendToStyle(code, id) : code
+        // Vite 热更新会绕过 SFC 主模块，直接把原始样式交给预处理器；先移除
+        // Sass 无法解析的 important utility 后，再由后续 CSS 阶段还原。
+        const preprocessorCode = query.vue && query.type === 'style'
+          ? normalizeUniAppXImportantApplyForSass(styleCode)
+          : styleCode
+        const preprocessor = resolvePreprocessorTransform(preprocessorCode, id, query.lang, {
+          isIosPlatform,
+          isNativeAppStyleTarget: isNativeAppStyleTarget(),
+        })
+        if (preprocessor) {
+          return preprocessor.result ?? (preprocessorCode !== code ? { code: preprocessorCode, map: null } : undefined)
+        }
+        return transformStyle(preprocessorCode, id, query, this)
+      },
     },
   }
   const cssPlugin: Plugin = {
@@ -261,6 +297,7 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
   const cssPlugins = [cssPlugin, cssPrePlugin]
 
   async function transformSfc(code: string, id: string, context: { addWatchFile?: (id: string) => void }) {
+    knownSfcSources.set(cleanUrl(id), code)
     if (isNativeAppBuildTarget(id)) {
       nativeLocalStyleModuleIds.add(id)
       nativeLocalStyleModuleIds.add(cleanUrl(id))
@@ -285,6 +322,7 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
       ...(disabledDefaultTemplateHandler ? { disabledDefaultTemplateHandler } : {}),
       ...(enableComponentLocalStyle ? { enableComponentLocalStyle } : {}),
       ...(enablePageLocalStyle ? { enablePageLocalStyle } : {}),
+      native: true,
       pageMatcher: resolvedUniAppXOptions.componentLocalStyles.pageMatcher,
       ...(isWebGeneratorTarget() && customAttributesEntities.length > 0 ? { webCustomAttributeDeep: true } : {}),
       ...(isWebGeneratorTarget() ? { onWebLocalStyleRules: (rules: string) => webLocalStyle.remember(id, rules) } : {}),
@@ -322,7 +360,7 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
       },
     },
     handleHotUpdate: {
-      order: 'post',
+      order: 'pre',
       async handler(ctx) {
         if (!isEnabled() || getResolvedConfig()?.command !== 'serve') {
           return
@@ -331,7 +369,12 @@ export function createUniAppXPlugins(options: CreateUniAppXPluginsOptions): Plug
           return
         }
         if (isWebGeneratorTarget() && UVUE_NVUE_RE.test(ctx.file) && typeof ctx.read === 'function') {
-          await transformSfc(await ctx.read(), ctx.file, this)
+          const source = await ctx.read()
+          if (hasUniAppXImportantApply(source)) {
+            ctx.server.ws.send({ type: 'full-reload', path: ctx.file })
+            return []
+          }
+          await transformSfc(source, ctx.file, this)
         }
         return webLocalStyle.handleHotUpdate(ctx) ?? nativeHmrReloader.handleHotUpdate(ctx)
       },

packages/weapp-tailwindcss/test/fixtures/uni-app-x/issue-1113.uvue

@@ -0,0 +1,9 @@
+<template>
+  <view class="!mt-6 mt-6!">important utility</view>
+</template>
+
+<style lang="scss">
+.important-apply {
+  @apply !mt-6 mt-6!;
+}
+</style>