unocss-preset-weapp

unocss-preset-weapp — 微信小程序 UnoCSS 预设#

资源概述#

unocss-preset-weapp 是 MellowCo 开发的微信小程序 UnoCSS 预设方案，GitHub 仓库 MellowCo/unocss-preset-weapp 目前拥有 456 stars / 40 forks（2026-08），MIT 协议，npm 包 unocss-preset-weapp 已发布 79 个版本（latest v66.0.2，2025-06-06），持续迭代至 2025-12-20。

作为 UnoCSS 小程序生态中 stars 最高的预设方案，unocss-preset-weapp 解决了微信小程序对 CSS 语法限制的核心痛点：不支持 :hover 伪类、不支持 * 通配选择器、不支持复杂属性选择器、rpx 与 rem 单位不兼容等。它是后续 unocss-applet 项目的前身之一，经过社区大量项目验证后仍然保持独立维护。

核心特点：

• 三种开发模式全覆盖：原生小程序（无框架）、Taro（React）、uni-app（Vue3）
• 丰富的预设和转换器：preset-weapp / preset-rem-rpx / transformer-attributify / transformer-class
• 79 个 npm 版本：从 2022-04 至今持续迭代，版本号跟随 UnoCSS 主版本对齐（当前 66.x）
• 完善的示例项目：提供原生小程序、Taro React、uni-app Vue3 三种完整示例

设计规范#

核心预设架构#

unocss-preset-weapp
  ├─ preset-weapp      → 基于 presetWind3 的小程序兼容预设
  │    ├─ 过滤不支持的选择器（* / :hover / :focus）
  │    ├─ 支持小程序特有的 hover-class 机制
  │    └─ 兼容小程序 CSS 语法限制
  ├─ preset-rem-rpx    → rem ↔ rpx 双向自动转换
  ├─ transformer-attributify → 小程序 Attributify 属性化模式
  └─ transformer-class → class 属性名转换（解决保留字冲突）

三种开发模式#

原生小程序

直接在 .wxml / .wxss / .js 中使用 UnoCSS 工具类，配合 Vite 构建插件处理样式编译。

Taro + React

在 JSX 中使用 UnoCSS 类名，支持 Attributify 属性化模式：

<View flex items-center justify-center p="4" bg="white">
  <Text text="red-500" font="bold">Hello Taro</Text>
</View>

uni-app + Vue3

在 Vue 模板中使用 UnoCSS 类名：

<template>
  <view class="flex items-center justify-center p-4 bg-white">
    <text class="text-red-500 font-bold">Hello uni-app</text>
  </view>
</template>

单位系统#

• rpx（responsive pixel）：小程序原生响应式单位，屏幕宽度 750rpx = 设备宽度
• rem ↔ rpx 转换：preset-rem-rpx 默认 1rem = 32rpx（设计稿 750px 宽度）
• px 直通：px 值不做转换，直接输出到 WXSS

Attributify 模式#

<!-- 传统 class 写法 -->
<view class="flex items-center justify-between p-4 bg-white rounded-lg shadow">
  <text class="text-lg font-bold text-gray-800">标题</text>
  <text class="text-sm text-gray-400">副标题</text>
</view>

<!-- Attributify 属性化模式 -->
<view flex items-center justify-between p="4" bg="white" rounded="lg" shadow>
  <text text="lg" font="bold" text="gray-800">标题</text>
  <text text="sm" text="gray-400">副标题</text>
</view>

transformer-class（class 保留字转换）#

小程序中某些 HTML 屇签/属性名与 CSS 属性冲突（如 block 是小程序标签），transformer-class 自动处理这些冲突：

<!-- 开发时写法 -->
<view class="block w-full h-screen">...</view>

<!-- 编译后（避免与 <block> 标签冲突） -->
<view class="u-block w-full h-screen">...</view>

审核规范#

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

• 生成的 WXSS 样式需符合小程序包体限制（微信主包 2MB / 总包 20MB）
• 原子化 CSS 类名较多时，WXSS 文件可能增大 10-30KB，建议使用 UnoCSS 按需生成
• Attributify 模式在百度/支付宝小程序的兼容性需额外测试
• transformer-class 的前缀（默认 u-）不应与项目已有 class 命名冲突

开发指南#

安装#

# 安装 UnoCSS + 预设
pnpm add unocss unocss-preset-weapp -D

# 或使用 yarn
yarn add unocss unocss-preset-weapp -D

原生小程序配置#

// vite.config.ts
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni' // 如果用 uni-app
import UnoCSS from '@unocss/vite'

export default defineConfig({
  plugins: [
    // uni(),  ← uni-app 项目启用
    UnoCSS(),
  ],
})

// uno.config.ts
import { defineConfig } from 'unocss'
import { presetWeapp, presetRemRpx, transformerAttributify, transformerClass } from 'unocss-preset-weapp'

export default defineConfig({
  presets: [
    presetWeapp(),
    presetRemRpx(),
  ],
  transformers: [
    transformerAttributify(),
    transformerClass(),
  ],
})

Taro + React 配置#

// uno.config.ts
import { defineConfig } from 'unocss'
import { presetWeapp, presetRemRpx, transformerAttributify } from 'unocss-preset-weapp'

export default defineConfig({
  presets: [
    presetWeapp(),
    presetRemRpx({ mode: 'rpx2rem' }), // Taro H5 端反向转换
  ],
  transformers: [
    transformerAttributify(),
  ],
})

// config/index.js (Taro Webpack 配置)
import UnoCSS from '@unocss/webpack'

export default {
  mini: {
    webpackChain(chain) {
      chain.plugin('unocss').use(UnoCSS())
    }
  },
  h5: {
    webpackChain(chain) {
      chain.plugin('unocss').use(UnoCSS())
    }
  }
}

uni-app + Vue3 配置#

// uno.config.ts — uni-app 最简配置
import { defineConfig } from 'unocss'
import { presetWeapp, presetRemRpx } from 'unocss-preset-weapp'

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

引入样式#

// 入口文件（main.ts / app.ts / app.js）
import 'uno.css'

常见陷阱#

1. 版本对齐：unocss-preset-weapp 的版本号跟随 UnoCSS 主版本（如 v66.x 对应 UnoCSS v66.x），升级时需同步。使用 pnpm why unocss 检查版本
2. Taro H5 构建问题：@unocss/webpack 在 Taro H5 端可能有 ModuleParseError，建议 H5 端使用 @unocss/cli 预生成方案
3. Attributify 与组件库冲突：uView / Vant 等组件库的自定义属性可能与 Attributify 冲突，使用 ignoreAttributes 排除
4. transformer-class 前缀：默认前缀 u- 可能与 uView 组件库的 class 命名冲突（uView 也用 u- 前缀），建议自定义前缀
5. 小程序自定义组件：小程序原生自定义组件（使用 Component 构建器）需确保组件 options 启用了 styleIsolation: 'apply-shared'，否则原子化样式无法穿透
6. 设计稿宽度：preset-rem-rpx 默认基于 750px 设计稿。若使用 375px 设计稿，需调整 baseFontSizeWithinpx 参数
7. 多端差异：同一套 UnoCSS 类名在不同小程序平台渲染效果可能略有差异（如抖音不支持部分 CSS 属性），需多端测试

生态资源#

上游依赖#

• UnoCSS：unocss/unocss — 即时原子化 CSS 引擎（Anthony Fu 开发，17K+⭐）
• @unocss/preset-wind3：Tailwind CSS 兼容预设

同类工具对比#

关联项目#

• unocss-applet：unocss-applet/unocss-applet — 受 unocss-preset-weapp 启发的小程序兼容层项目
• weapp-tailwindcss：sonofmagic/weapp-tailwindcss — Tailwind CSS 小程序方案（1841⭐）

示例项目#

• Taro + React 示例：examples/taro-react
• uni-app + Vue3 示例：examples/uni-app-vue3
• 原生小程序示例：examples/weapp-native

版本更新#

• 当前版本：unocss-preset-weapp v66.0.2（npm，2025-06-06）
• npm 版本数：79 个版本（2022-04 至 2025-06，跟随 UnoCSS 主版本号对齐）
• GitHub 活跃度：456⭐ / 40 forks，最后推送 2025-12-20
• 兼容性：
  • UnoCSS v0.53+ ~ 66.x（版本号对齐策略）
  • 原生微信小程序 ✅
  • Taro 3.x / 4.x + React ✅
  • uni-app Vue3 + Vite ✅
  • Vite + Webpack5 双构建工具 ✅
• 核心导出：
  • presetWeapp() — 小程序兼容主预设
  • presetRemRpx() — rem ↔ rpx 转换
  • transformerAttributify() — Attributify 模式
  • transformerClass() — class 保留字转换
• 版本演进：
  • v0.x ~ v0.5x：独立版本号，基于 UnoCSS v0.x
  • v55.x+：开始跟随 UnoCSS 主版本号
  • v66.x（当前）：适配 UnoCSS v66.x ESM-only
• 核实记录：2026-08-10 核实 GitHub 456⭐/40 forks，npm v66.0.2 / 79 versions，最后推送 2025-12-20，MIT 协议