跳到主要内容

HBuilderX

提示

主线接入文档已合并到 uni-app HBuilderX 使用方式。本页保留给旧链接和 Tailwind CSS 4 专项排障。

警告

这条 HBuilderX（uni-app） 路线对应 Vue3 + Vite，属于推荐方案。

如果你已经使用 HBuilderX 工作流、插件生态或发布流程，可以直接按本文接入；如果你希望更贴近当前仓库推荐的开发方式，也可以评估 weapp-vite。

1. 安装​

# 初始化 package.json
npm init
# 安装包
npm install -D tailwindcss weapp-tailwindcss

2. 添加 vite.config.ts​

vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import path from 'node:path'

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss({
      rem2rpx: true,
      tailwindcssBasedir: __dirname,
      cssEntries: [
        // Tailwind CSS 入口文件绝对路径
        path.resolve(__dirname, './src/app.css'),
      ],
    }),
  ],
});

tailwindcss@4 必须配置 cssEntries 并且使用绝对路径，否则 weapp-tailwindcss 无法稳定定位 CSS 入口。

3. 添加样式​

在 src/app.css 中引入 Tailwind CSS，这个文件会作为 Tailwind CSS 入口：

src/app.css
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";
关于 @import 'tailwindcss'

生成模式下，推荐在 Tailwind CSS 4.x 入口里直接写 @import 'tailwindcss'。WeappTailwindcss 会根据 target: 'weapp' 生成小程序目标 CSS。

这也能继续复用官方文档和 IntelliSense 识别的写法 @import 'tailwindcss'，以获得更好的 IDE 智能提示 支持。

存量项目中已经存在的 @import 'weapp-tailwindcss/index.css' 仍然可以继续使用，适合暂时不调整 CSS 入口的 v4 项目。

不论使用哪种入口，都请确保 cssEntries 指向纯 .css 文件，并且不要额外注册 @tailwindcss/postcss 或 @tailwindcss/vite。

为了 IDE 智能提示，需要在 VS Code 里显式告诉 Tailwind CSS IntelliSense 哪个文件是 Tailwind 4 的 CSS 入口。最直接的做法是把它指向真实生效的 src/app.css：

.vscode/settings.json
{
  "tailwindCSS.experimental.configFile": "src/app.css"
}

如果你更想单独放一个“只给编辑器识别”的文件，也可以额外创建 src/main.css：

src/main.css
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";

然后把 experimental.configFile 指向它：

.vscode/settings.json
{
  "tailwindCSS.experimental.configFile": "src/main.css"
}

这个 src/main.css 只用于 IntelliSense，不要在 App.vue / App.uvue 里实际引入。应用运行时仍然使用 src/app.css 作为 Tailwind CSS 入口。

@source 扫描范围排障​

问题现象​

如果你的 uni-app / uni-app x 项目把第三方插件或依赖直接放在根目录下的 uni_modules，同时 Tailwind 4 的 CSS 入口没有显式排除它，那么 Tailwind 4 也可能把依赖源码、README 示例文本或构建产物误当成候选，最终生成无意义样式。

根因​

根因仍然是扫描范围过宽。Tailwind 4 会根据 @source 收集候选，如果把 uni_modules 一并扫进去，就会把第三方目录中的非业务文本也纳入提取范围。

推荐配置​

对于 HBuilderX 工作流，推荐在 Tailwind 4 的 CSS 入口里显式排除：

src/main.css
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";

最佳实践​

  • @source 应尽量只覆盖业务源码目录
  • 默认排除 uni_modules、node_modules、dist、unpackage、文档和生成产物
  • 如果必须扫描某个 uni_modules 包，只精确包含真正承载模板类名的文件，不要扫描整个目录

这里要写 @import "tailwindcss"，因为 tailwindcss-intellisense 当前用于触发 v4 设计系统加载的判断只认 @import "tailwindcss" 或 @theme {}，并不认 @import "weapp-tailwindcss/index.css"。

添加 @source not "unpackage"; 是为了避免 HBuilderX 差量编译死循环问题；再加上 @source not "uni_modules";，则可以避免把第三方依赖源码一并扫进 Tailwind 4 的候选集合。

注意

千万不要在 uni.scss 中去引入 tailwindcss, uni.scss 本质上走的是 scss.additionalData, 它会在每一个 scss 文件的开头，都去添加 uni.scss 里的文件内容

所以这相当于你每个 scss/ vue 文件里面，都加了 tailwindcss 引入，那 css 体积就爆炸了

在页面里写一段可观察的工具类，例如 bg-[#123456] text-[#654321]，再运行到微信开发者工具检查效果。

布局限制​

  • uni-app x 中不要使用 gap、gap-x-*、gap-y-*
  • uni-app x 中也不要使用 space-x-*、space-y-*
  • 需要间距时，请直接对子项写 mt-* / ml-*，或封装固定结构的间距组件

参考模板​

SPONSORED
Easysearch
企业级的分布式搜索型数据库