跳到主要内容

uni-app x 配置参考

本页集中说明 uniAppX() preset 的配置项。接入步骤见 uni-app x 快速开始。

支持基线​

  • weapp-tailwindcss 5.3.3
  • Tailwind CSS 4.x
  • Node.js ^22.18.0 || >=24.11.0
  • HBuilderX >=5.11
  • 目标：HBuilderX Web、小程序、Android、iOS 与 HarmonyOS

安装​

npm install -D tailwindcss weapp-tailwindcss

使用 HBuilderX 管理的 uni-app x 工程时，依赖应安装在工程根目录；不要额外注册 @tailwindcss/vite 或 @tailwindcss/postcss。

最小配置​

vite.config.ts
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { uniAppX } from 'weapp-tailwindcss/presets'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss(uniAppX({
      base: projectRoot,
      cssEntries: [resolve(projectRoot, 'main.css')],
    })),
  ],
})

cssEntries 只告诉生成器 Tailwind CSS 入口，仍必须在 App.uvue 或真实应用入口中导入 main.css。不要在同一次构建中再注册 @tailwindcss/postcss 或 @tailwindcss/vite。

uniAppX() 配置项​

配置项类型默认值说明
basestring必填uni-app x 工程根目录。建议使用 fileURLToPath(import.meta.url) 推导，避免 HBuilderX 改变工作目录。
cssEntriesstring[]自动识别Tailwind CSS 4 入口。多入口时全部列出，建议传绝对路径。
rem2rpxboolean | object—将 rem 转为 rpx，属于 preset 顶层配置。
unitsToPxboolean | object—长度单位转 px 的配置。
unitConversionobject | false—按平台或统一规则转换 CSS 单位。
generatorobject | false自动推断Tailwind 生成器配置。Web/H5 会自动使用 target: 'web' 与 Web 兼容处理。
uniAppXboolean | object原生 App 自动启用控制 uvue/App 适配、局部样式和不兼容 utility 处理。
componentLocalStylesboolean | objecttrueuniAppX.componentLocalStyles 的快捷入口。
uvueUnsupported'error' | 'warn' | 'silent''warn'uvue 不支持的 utility 如何处理。
customAttributesICustomAttributes—为 class 之外的模板属性增加类名转译。
resolvePackageResolvingOptions工程 node_modules自定义 Tailwind 包解析路径。
rawOptionsUserDefinedOptions—透传未被 preset 快捷入口覆盖的核心配置。

rem2rpx、unitsToPx 和 unitConversion 不应放在 cssOptions 下；它们是 uniAppX() 的顶层选项。

局部样式与 uvue 兼容​

uniAppX({
  base: projectRoot,
  cssEntries: [resolve(projectRoot, 'main.css')],
  componentLocalStyles: {
    enabled: true,
    onlyWhenStyleIsolationVersion2: false,
    componentMatcher: id => /(?:^|\/)layouts\/.+\.uvue$/.test(id),
    pageMatcher: id => /(?:^|\/)pages\/.+\.uvue$/.test(id),
  },
  uvueUnsupported: 'warn',
})
  • componentMatcher 和 pageMatcher 收到已移除 query/hash、统一为正斜杠的模块路径。
  • 传入 matcher 会覆盖对应的默认 components 或 pages 目录规则；需要保留默认目录时在回调中一并匹配。
  • onlyWhenStyleIsolationVersion2 默认是 true，只有 manifest.json 使用样式隔离版本 2 时才启用组件局部样式。
  • uvueUnsupported: 'error' 适合在 CI 强制发现不兼容 utility；'silent' 只建议用于已知且明确处理的场景。

Tailwind CSS 入口​

main.css
@import "tailwindcss" source(none);

@source "./App.uvue";
@source "./pages/**/*.{uvue,uts}";
@source "./components/**/*.{uvue,uts}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";

在 App.uvue 的全局样式中实际导入：

<style>
@import './main.css';
</style>

多端边界​

  • uni-app x 原生 App 不需要配置 generator.target: 'app'；原生目标继续由 uniAppX、平台环境和单位转换处理。
  • Web/H5 不要手动关闭 uniAppX，否则 .uvue 模板中的任意值和暗色工具类可能无法按安全选择器处理。
  • cssEntries 不会替代构建图导入；缺少真实 @import 时会出现“已生成但页面无样式”。
  • unpackage、dist 和 uni_modules 不应无差别加入 @source。
  • gap、space-x-* 和 space-y-* 在原生 uvue 端不能作为通用布局方案，应按目标端限制改用子项间距。

验证​

请在自己的 HBuilderX 项目中运行对应平台的开发或构建流程，并按以下清单验收：

  • Web、小程序、Android、iOS 和鸿蒙分别生成实际目标产物，检查真实 CSS 后缀和入口文件。
  • cssEntries 指向的入口确实被项目引入，扫描范围覆盖页面、组件和布局源码。
  • 单位转换、componentLocalStyles、uvueUnsupported 与 customAttributes 的结果符合目标平台限制。
  • HBuilderX、模拟器或设备中的运行时效果与构建产物一致，不要只用 H5 构建成功作为原生结论。