uni-app x 专题
这篇文档适合谁
- 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
- 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案
- 已经使用 HBuilderX 运行或发布 uni-app x 项目
当前支持范围
weapp-tailwindcss@5 同时支持 Tailwind CSS 3 和 Tailwind CSS 4。uni-app x 项目建议通过 WeappTailwindcss(uniAppX(...)) 注册插件，Tailwind 的生成和小程序/App 转译都交给 weapp-tailwindcss。
| Tailwind 版本 | 入口方式 | 扫描方式 | 当前验证 |
|---|---|---|---|
| Tailwind CSS 3 | @tailwind base; / components / utilities | tailwind.config.js 的 content | HBuilderX 小程序、Android、iOS |
| Tailwind CSS 4 | @import "tailwindcss" source(none); | CSS 入口里的 @source | HBuilderX 小程序、Android、iOS |
本地 E2E
HBuilderX 依赖本机安装环境，所以 Android/iOS App E2E 只在本地运行，不放进 CI/CD。仓库里对应的命令是 pnpm e2e:hbuilderx:local:app、pnpm e2e:hbuilderx:local:android 和 pnpm e2e:hbuilderx:local:ios。
最快开始
- 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可
- 想了解每一步：前往「手动集成」教程 → 快速集成
开发建议
- 推荐编辑器协作：用 VS Code 写代码，用 HBuilderX 负责运行与构建
- 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App（Android/iOS/鸿蒙）。先用 Android 模拟器打通路径，跨端成本最低
- 组件语义注意：原生 App 端文字需放在
<text>标签，且文本样式需要直接作用在该元素上 - 渐进增强：若某些样式在 App 端受限，优先保证 Android 端体验，再按需做条件编译适配小程序/Web
布局能力边界
uvue原生 App 端不支持gap、gap-x-*、gap-y-*，包括所有 grid gap 与 flex gap 场景space-x-*、space-y-*在uni-app x中也不再支持，请不要使用- 需要稳妥跨端时，优先改为对子项显式写
mt-*/ml-*，或封装Stack一类组件统一处理间距
为什么推荐先用 Android
- 原生端样式约束更严格，例如文本必须使用
<text>，许多 CSS 特性仍在补齐中 - 如果你的页面在 Android 端无告警、展示正确，迁移到小程序与 Web 的心智负担会小很多
- iOS/鸿蒙的调试门槛更高（设备/系统要求），多数团队以 Android 作为优先目标更务实
常见问题
VS Code 对 uvue/uts 的高亮与跳转
安装官方语言服务插件：
- ID: dcloud-ide.hbuilderx-language-services
- 说明: 支持 uni-app x 项目的提示、悬浮、转到定义、查找引用、校验等
- 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services
Tailwind CSS 智能提示
VS Code 原生不识别 uvue/uts，建议为 Tailwind 扩展加上语言映射。在项目根目录创建 .vscode/settings.json：
.vscode/settings.json
{
"tailwindCSS.includeLanguages": {
"uvue": "html",
"uts": "javascript"
}
}
运行方式
uni-app x 的运行和构建仍以 HBuilderX 为准。需要命令行自动化时，可以使用 HBuilderX CLI；本仓库的本地 E2E 就是通过 hbuilderx launch 跑 Web、小程序和 App 目标。
接下来
- 跟着步骤手动完成集成：快速集成
- 直接基于模板起步：uni-app x + Tailwind 模板（HBuilderX）
