@uni-helper/unocss-preset-uni

@uni-helper/unocss-preset-uni — uni-app 专用 UnoCSS 预设#

资源概述#

@uni-helper/unocss-preset-uni 是 uni-helper 官方团队打造的 uni-app 专属 UnoCSS 预设，GitHub 仓库 uni-helper/unocss-preset-uni 目前拥有 128 stars / 7 forks（2026-08），MIT 协议，TypeScript 编写，npm 包 @uni-helper/unocss-preset-uni 已发布 14 个版本（latest v0.3.1，2026-07-09）。

uni-app 跨端开发中，H5 端和小程序端对 CSS 的支持差异巨大：H5 支持完整的 CSS 语法（:hover、* 选择器、attributify 等），而小程序有严格限制。开发者通常需要手动配置两套预设。unocss-preset-uni 的核心价值是自动平台切换：

H5 环境：启用 @unocss/preset-wind3（默认）或 @unocss/preset-wind4，完整支持 Tailwind CSS 语法
小程序环境：自动切换到 @unocss-applet/preset-applet（unocss-applet 的小程序兼容版），处理选择器限制、hover-class 转换等

一行 presetUni() 即可完成全部配置，无需手动判断平台、无需写条件分支。与 uni-helper 生态的 create-uni（脚手架）、vite-plugin-uni-pages（路由）、vitesse-uni-app（起步模板）形成完整的 uni-app + UnoCSS 开发体验。

设计规范#

自动平台切换原理#

code

uni-app 构建流程
  ├─ H5 平台 → presetWind3/4（标准 Tailwind 语法）
  └─ 小程序平台（mp-weixin/mp-alipay/...）
       └─ presetApplet（@unocss-applet/preset-applet）
            ├─ 过滤小程序不支持的选择器
            ├─ hover: → hover-class 转换
            └─ attributify 属性化模式适配

按平台条件样式#

unocss-preset-uni 独有的平台变体功能，让开发者为不同平台编写差异化样式：

code

<!-- 微信小程序显示红色，其他平台显示蓝色 -->
<view class="mp-weixin:text-red-500 text-blue-500">
  跨平台文字
</view>

<!-- 仅 H5 端显示阴影 -->
<view class="h5:shadow-lg h5:hover:shadow-xl">
  卡片
</view>

单位系统#

rem ↔ rpx 自动转换：内置 presetRemRpx，小程序端 rem 自动转 rpx，H5 端 rpx 自动转 rem
设计稿宽度：默认 750px（uni-app 标准），支持自定义
基准字号：1rem = 32rpx（默认），可配置

Attributify 模式#

code

<!-- 传统写法 -->
<view class="flex items-center justify-center p-4 bg-white rounded-lg">
  <text class="text-red-500 font-bold text-lg">标题</text>
</view>

<!-- Attributify 模式 -->
<view flex items-center justify-center p="4" bg="white" rounded="lg">
  <text text="red-500" font="bold" text="lg">标题</text>
</view>

审核规范#

unocss-preset-uni 为开发工具，不涉及平台审核。但需注意：

生成的 WXSS 样式需符合小程序包体限制（主包 2MB）
过多原子化类名可能增大样式文件体积，UnoCSS 默认按需生成可缓解
平台变体（如 mp-weixin:）在小程序端编译后会移除其他平台的样式，不会泄露平台判断逻辑
Attributify 模式在某些小程序平台（百度/快手）的兼容性需额外测试

开发指南#

安装#

code

# 安装预设 + 依赖
pnpm add @uni-helper/unocss-preset-uni -D
pnpm add unocss unocss-applet -D

# 或使用 yarn/npm
yarn add @uni-helper/unocss-preset-uni unocss unocss-applet -D

版本对齐：UnoCSS ~66.7.5、unocss-applet ^0.13.8（pnpm 会按 peerDependencies 自动提示）

配置 Vite#

code

// vite.config.ts（支持 HBuilderX）
import Uni from '@dcloudio/vite-plugin-uni'
import { defineConfig } from 'vite'

export default async () => {
  const UnoCSS = (await import('unocss/vite')).default
  return defineConfig({
    plugins: [Uni(), UnoCSS()],
  })
}

配置 UnoCSS 预设#

code

// uno.config.ts
import { defineConfig } from 'unocss'
import { presetUni } from '@uni-helper/unocss-preset-uni'

export default defineConfig({
  presets: [
    presetUni(),
  ],
})

以上配置即完成了全部设置。presetUni() 默认启用：

presetWind3（H5）/ presetApplet（小程序）
presetRemRpx（rem ↔ rpx）
presetAttributify（Attributify 模式）
平台变体支持

自定义配置#

code

// uno.config.ts — 完整自定义
import { defineConfig } from 'unocss'
import { presetUni } from '@uni-helper/unocss-preset-uni'

export default defineConfig({
  presets: [
    presetUni({
      // 切换到 Wind4
      uno: { preset: 'wind4' },
      // 关闭 Attributify
      attributify: false,
      // 自定义 rem-rpx 转换
      remRpx: { mode: 'rem2rpx', baseFontSizeWithinpx: 32 },
      // 关闭平台变体
      platform: false,
    }),
  ],
})

在入口文件引入样式#

code

// main.ts
import 'uno.css'

在 Vue 模板中使用#

code

<template>
  <view class="flex flex-col items-center p-4 bg-gray-50 min-h-screen">
    <view class="w-full bg-white rounded-2xl p-6 shadow-sm">
      <text class="text-2xl font-bold text-gray-900">Hello uni-app</text>
      <text class="text-sm text-gray-500 mt-2">Powered by UnoCSS</text>
    </view>
    <!-- 平台变体：仅微信小程序显示 -->
    <view class="mp-weixin:bg-green-50 mp-weixin:p-4 mp-weixin:rounded-lg mt-4">
      <text class="text-green-600">微信小程序专属内容</text>
    </view>
  </view>
</template>

常见陷阱#

版本对齐问题：UnoCSS、unocss-applet 和 unocss-preset-uni 三者版本必须对齐（peerDependencies 约束）。升级时任一包版本不匹配会导致构建失败。建议锁定版本号
HBuilderX 兼容：HBuilderX 项目使用 .vue 配置文件（非 .mts），需使用支持 HBuilderX 的配置方式（见上方 vite.config.ts 示例）
Attributify 冲突：某些 Vue 组件 props 名可能与 UnoCSS 工具类冲突（如 block、container），通过 ignoreAttributes 选项排除
icons 预设：如需使用 @unocss/preset-icons，需单独安装并手动加入 presets 数组
小程序自定义组件：原生小程序自定义组件（non-vue）无法使用 UnoCSS，需使用原生 WXSS
Pure ESM：UnoCSS v0.59+ 只提供 ESM 支持，CommonJS 项目（如旧版 Webpack 配置）需做 ESM 适配

生态资源#

上游依赖#

UnoCSS：unocss/unocss — 即时原子化 CSS 引擎（Anthony Fu 开发）
unocss-applet：unocss-applet/unocss-applet — 小程序兼容层（253⭐，presetApplet / presetRemRpx / transformerHover）

uni-helper 生态#

create-uni：uni-helper/create-uni — uni-app 脚手架工具（303⭐）
vite-plugin-uni-pages：uni-helper/vite-plugin-uni-pages — 文件路由（204⭐）
vitesse-uni-app：uni-helper/vitesse-uni-app — 起步模板（571⭐），已内置 unocss-preset-uni
uni-typed：uni-helper/uni-typed — TypeScript 类型支持（86⭐）

工具	定位	适用场景
unocss-preset-uni	uni-app 一体化预设	uni-app 项目零配置使用 UnoCSS
unocss-applet	小程序兼容层（底层）	Taro/原生小程序项目手动配置
unocss-preset-weapp	微信小程序专用预设	仅微信小程序项目
weapp-tailwindcss	Tailwind CSS 方案	偏好 Tailwind 生态的项目

集成模板#

unibest：feige996/unibest — uni-app 最佳实践模板（2187⭐），内置 UnoCSS
vitesse-uni-app：官方轻量模板，开箱即用

版本更新#

当前版本：@uni-helper/unocss-preset-uni v0.3.1（npm，2026-07-09）
npm 版本数：14 个版本（持续迭代）
兼容性：
- UnoCSS ~66.7.5（peerDependencies 锁定）
- unocss-applet ^0.13.8（peerDependencies 锁定）
- uni-app Vue3 + Vite（HBuilderX 兼容）
支持平台：
- H5（presetWind3/4）
- 微信小程序 / 支付宝小程序 / 百度小程序 / 抖音小程序 / QQ 小程序（presetApplet）
- App 端（presetWind3/4）
核心选项：
- uno.preset：wind3（默认）/ wind4
- uno.disabled：关闭 wind 预设
- attributify：Attributify 模式（默认 true）
- remRpx：rem ↔ rpx 转换（默认开启）
- platform：平台变体（默认开启）
核实记录：2026-08-10 核实 GitHub 128⭐/7 forks，npm v0.3.1 / 14 versions，最后推送 2026-07-09，MIT 协议

@uni-helper/unocss-preset-uni

特性

详细文档