uni-app cli vue3 vite

提示

主线接入文档已合并到 uni-app CLI Vue3 Vite。本页保留给旧链接和 Tailwind CSS 4 专项排障。

1. 安装

npm

npm install -D tailwindcss weapp-tailwindcss

Yarn

yarn add --dev tailwindcss weapp-tailwindcss

pnpm

pnpm add -D tailwindcss weapp-tailwindcss

Bun

bun add --dev 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'

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss({
      rem2rpx: true,
    }),
  ],
});

常规 Vite 项目会自动识别被引入的 Tailwind CSS 入口。只有多入口、入口未被框架引入、自动识别失败等场景，才需要手动配置 cssEntries。 Tailwind CSS 4 入口建议放在纯 .css 文件里，不要直接写进 scss、less 等预处理样式文件。

3. 添加样式

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

src/app.css

@import "tailwindcss";
@source not "dist";
@source not "../src/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 "dist";
@source not "../src/uni_modules";

然后把 experimental.configFile 指向它：

.vscode/settings.json

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

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

@source 扫描范围排障

问题现象

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

根因

根因和 Tailwind v3 的 content 误扫描类似，本质上都是扫描范围过宽，把业务源码以外的第三方内容也纳入了提取范围。

推荐配置

对于 uni-app cli 项目，推荐在 Tailwind 4 的 CSS 入口里显式排除：

src/main.css

@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";

最佳实践

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

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

注意

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

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

接着直接运行 npm run dev:mp-weixin，

微信开发者工具导入这个项目，即可看到效果

参考模板

uni-app-tailwindcss-v4