萧寂

Appearance

微信小程序使用tailwindcss的配置(非常详细) ​

这里使用了第三方库来实现：https://weapp-tw.icebreaker.top/

官方配置步骤一： https://weapp-tw.icebreaker.top/docs/quick-start/native/install

官方配置步骤二：https://weapp-tw.icebreaker.top/docs/quick-start/native/install-plugin

我下面的操作步骤跟官方步骤（步骤一和步骤二连起来）一比一还原的，避免某天官网挂了或者教程丢了

官网上面还有框架类的配置，如uniapp配置，个人建议uniapp和原生小程序建议看这个，其他的使用官方版的tailwindcss去配置就可以了，因为uniapp会编译到小程序里面，小程序里面有很多不支持原生的选择器之类的，如果项目牵扯到小程序，建议看这个文档进行配置

一. 安装与配置 tailwindcss ​

前言​ ​

很荣幸，我们在 weapp-tailwindcss@3.2.0 版本开始，引入了微信小程序原生支持的能力。 (其他平台的原生小程序开发，也非常容易兼容)

接下来让我们看看，如何进行使用吧！

本教程演示的是，使用微信开发者工具创建的原生 js 小程序，以及原生 js skyline 小程序使用 tailwindcss 的方式

运行环境​ ​

请确保你的 nodejs 版本 >=16.6.0。目前低于 16 的长期维护版本(偶数版本) 都已经结束了生命周期，建议安装 nodejs 的 LTS 版本，详见 nodejs/release。

假如你安装的 nodejs 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 --ignore-engines 参数进行 nodejs 版本的忽略 。

创建项目​ ​

打开微信开发者工具, 点击 + 创建一个项目，依次选择:

  1. AppID 使用测试号
  2. 开发模式: 小程序
  3. 后端服务: 不使用云服务
  4. 模板选择: 第二项选择 基础
  5. 选择 JS 基础模板

使用 JS 基础模板创建的项目，依然可以使用 Typescript

首先安装本插件前，我们需要把 tailwindcss 对应的环境和配置安装好。

0. 初始化 package.json​ ​

首先，假如你使用原生的 JS 模板创建的项目。

在创建的项目目录下，是没有 package.json 文件 (原生的 TS 模板有这个文件), 你需要执行命令:

npm init -y，快速创建一个 package.json 文件在你的项目下

1. 使用包管理器安装 tailwindcss​ ​

然后执行:

bash
npm i -D tailwindcss postcss autoprefixer
# 初始化 tailwind.config.js 文件
npx tailwindcss init

如果在初始化命令报错如下(没碰到这个报错就不用管了):

js
PS D:\myProject\toolBox> npx tailwindcss init
npm error could not determine executable to run
npm error A complete log of this run can be found in: C:\Users\zsx27\AppData\Local\npm-cache\_logs\2025-06-12T08_12_18_684Z-debug-0.log
PS D:\myProject\toolBox>
PS D:\myProject\toolBox>

需要卸载已安装版本,降低到3版本,如下代码

js
npm uninstall tailwindcss
npm install tailwindcss@3.4.17 -D

这样 tailwindcss 就被安装到你项目本地了

2. 配置 tailwind.config.js​ ​

tailwind.config.js 是 tailwindcss 的配置文件，我们可以在里面配置 tailwindcss 的各种行为。

这里给出了一份 JS微信小程序 通用示例，具体要根据你自己项目的目录结构进行配置

tailwind.config.js

js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // 添加你需要提取的文件目录
    'components/**/*.{wxml,js,ts}',
    'pages/**/*.{wxml,js,ts}',
    // 不要使用下方的写法，这会导致 vite 开发时监听文件数量爆炸
    // '**/*.{js,ts,wxml}', '!node_modules/**', '!dist/**'
  ],
  // blocklist: ['container'], // 阻止tailwindcss对某些类进行打包
  // 假如你使用 ts 模板，则可以使用下方的配置
  // content: ['miniprogram/**/*.{ts,js,wxml}'],
  corePlugins: {
    // 小程序不需要 preflight 和 container，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它
    preflight: false,
    container: false,
  }
}

3. 在项目目录下创建 postcss.config.js 并注册 tailwindcss​ ​

内容如下:

postcss.config.js

js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

这个文件和 tailwind.config.js 平级

4. 引入 tailwindcss​ ​

在你的小程序项目入口 app.wxss 文件中，引入 tailwindcss 使它在小程序全局生效

css
@tailwind base;
@tailwind components;
@tailwind utilities;

在 app.wxss 加入这一段代码之后，微信开发者工具会报错。不用担心，这是因为我们还没有完全配置好。

接下来，赶紧进入下一步，安装 weapp-tailwindcss 并运行吧！

二. 安装这个插件并运行 ​

安装插件​ ​

在项目目录下，执行:

bash
npm i -D weapp-tailwindcss weapp-vite

这样 weapp-tailwindcss 和 weapp-vite 就被安装在你的本地了

执行初始化命令​ ​

在命令行中运行

js
npx weapp-vite init

这个命令会对现有的原生小程序项目，进行 weapp-vite 的初始化

执行后，会发现主要有许多文件改动，CLI 主要做了 3 件事情:

  • 创建 vite.config.ts 文件，这个是 weapp-vite 和 vite 的配置文件
  • 修改 package.json, 添加 dev 和 build 开发和构建脚本，还有构建 npm 和打开微信开发者工具
  • 修改 project.config.json 内容，来适配构建产物
  • 添加适配 vite 的 dts 和 tsconfig.json

安装所有的依赖包​ ​

在执行完成 weapp-vite init 初始化命令之后，我们需要在项目里执行一下安装命令:

npm i

注册插件​ ​

给 package.json 添加下列脚本:

package.json

json
{
  "scripts": {
    "postinstall": "weapp-tw patch"
  }
}

然后在你的 vite.config.ts 里对插件进行注册:

vite.config.ts

ts
import { defineConfig } from 'weapp-vite/config'
import { UnifiedViteWeappTailwindcssPlugin as uvwt } from 'weapp-tailwindcss/vite'

export default defineConfig({
  plugins: [
    uvwt({
      rem2rpx: true,
    }),
  ],
})

开始运行​ ​

使用 npm run dev 进入开发模式, 此模式带有热更新的，主要用于开发

使用 npm run build 进行构建

不论是 npm run dev 还是 npm run build, 他们的构建产物，都在工程目录下的 dist 目录

使用微信开发者工具，直接导入工程目录，然后即可预览效果！如果没效果的话继续往下看,大概率是因为小程序组件的隔离性,下面有解决办法

注意不是导入 dist 目录，是你工程的根目录! 通常是 dist 的父级目录，不要搞错了！

配置好的模板​ ​

假如你配置不成功，你可以参考以下模板进行配置文件对比:

weapp-vite-tailwindcss-template

或者直接执行命令:

bash
npx weapp-vite create my-app

此命令会在当前目录下，创建一个目录名为 my-app 的 weapp-vite + weapp-tailwindcss 集成模板

原生组件样式的隔离性​ ​

提示

发现很多用户，在使用原生开发的时候，经常会问，为什么 tailwindcss 样式对自定义组件不生效。

这可能有以下几个原因:

  1. 代码文件不在 tailwind.config.js 的 content 配置内
  2. 原生小程序组件是默认开启 组件样式隔离 的，默认情况下，自定义组件的样式只受到自定义组件 wxss 的影响。而 tailwindcss 生成的工具类，都在 app.wxss 这个全局样式文件里面。不属于组件内部，自然不生效。

这时候可以在你组件的 json 文件配置中，设置下面一行 styleIsolation 来开启样式共享:

custom-component.json

json
{
  "styleIsolation": "apply-shared"
}

apply-shared 表示页面 wxss 样式将影响到自定义组件，但自定义组件 wxss 中指定的样式不会影响页面；

来让组件应用到 app.wxss 里的样式。

更多的文档详见: 微信小程序相关开发文档

想了解更多 weapp-vite​ ​

更多场景和配置，请查看 weapp-vite 文档网站

萧寂173专属博客，v1.0.0.4