# weapp-tailwindcss 文档索引

> Tailwind CSS 小程序适配方案，覆盖 uni-app、taro、rax、mpx、原生等场景的官方文档合集。

完整文档合辑，适合离线或单文件加载：
- quick-start/* 给出接入步骤与常见框架示例，options/*、api* 提供配置与 API 细节，ai/* 收录提示词与工作流。
- 内容按上手优先排序，并保留关键 frontmatter 供模型摘要与索引。

## 简介


<!-- :::tip
自从 `2.3.3` 版本开始，我发布了一个额外的包叫 [`weapp-tailwindcss`](https://www.npmjs.com/package/weapp-tailwindcss),它和 [`weapp-tailwindcss-webpack-plugin`](https://www.npmjs.com/package/weapp-tailwindcss-webpack-plugin) 代码版本完全一致，且保持发布版本的同步。以后可以都去安装那个包(当然安装现在这个包也行)。为什么要这么做的原因，主要是因为 `weapp-tailwindcss-webpack-plugin` 这个名字，已经不适合现在这种，多插件并存的状态了，为了以后的发展改个名字。
::: -->

## 总览

由于小程序运行时，本身有自己的一套 **独特的** 技术规范标准。这导致你无法使用 `web` 开发中的很多的特性，

你也无法 **直接** 使用像 [`tailwindcss`](https://www.tailwindcss.com/) 这种原子化 `css` 生成器来提升你的开发效率。

而 `weapp-tailwindcss` 就能让你，在小程序开发中使用 `tailwindcss` **大部分** 特性。

它支持目前上所有使用 `webpack` 和 `vite` 的主流多端小程序框架和使用 `webpack` / `gulp` 的原生小程序打包方式。

你可以很容易在各个框架，或原生开发中集成 `tailwindcss`。

现在，就让我们开始使用吧！

:::info
从本质上讲，它是一个字符串转义器。它负责把 `tailwindcss` 中，所采集的类名，以及生成的结果，转化成小程序中可以接受的方式。
:::

## 环境要求

- Node.js `^20.19.0` 或 `>=22.12.0`（建议 LTS）

## Why `weapp-tailwindcss`?

- ✅ 自动处理所有文件：以微信小程序为例，不但可以处理和转义 `wxml` / `wxss`，还能处理 `js` 和 `wxs` 产物
- ✅ 支持最原生的小程序开发，也支持许多框架如 `taro` , `uni-app` , `mpx` , `rax` 等等..
- ✅ 提供多种使用方式，方便项目集成：包括 `webpack` / `vite` / `gulp` 插件和直接的 `nodejs api`
- ✅ 生态好，解决方案丰富，提供大量现成模板，可以利用许多 `tailwindcss` 现有的生态来构建小程序。
- ✅ 高效的解析和缓存机制，热更新响应时间快
- ✅ 贴合 `tailwindcss` 的设计思路，智能提示友好

## 快速开始 :rocket:

### 🔥 Tailwind CSS @3.x

`weapp-tailwindcss` 主要提供了 `3` 种使用方式:

#### 👉 [1. 框架类( `taro` , `uni-app` , `mpx` )小程序开发的快速开始](/docs/quick-start/install)

#### 👉 [2. 原生小程序开发的快速开始](/docs/quick-start/native/install)

#### 👉 [3. 可直接使用的各个框架的小程序模板](/docs/community/templates)

### 🧪 Tailwind CSS @4.x

#### 👉 [Tailwindcss@4.x 快速开始](/docs/quick-start/v4)

## 演示视频

<iframe src="//player.bilibili.com/player.html?aid=835925684&bvid=BV1fg4y1D7xx&cid=1398844948&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

## 另外特别感谢 [舜岳同学](https://space.bilibili.com/475498258) 为 `weapp-tailwindcss` 制作的视频

<iframe src="//player.bilibili.com/player.html?aid=1850100366&bvid=BV1kp421Z7HL&cid=1428939742&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## 小程序多主题方案


## 自由的 web 方案

对于 `web` 来说，多主题色的需求是非常常见的，比如 `暗黑模式` 就是一个极其常见的需求，

`web` 上的解决方案无非就是，通过动态切换 `css` 变量的值达成效果，或者通过 `.dark / [data-theme]` 选择器，包裹暗黑模式下页面和组件的样式，通过增加选择器的优先级，来覆盖默认的样式等等...

那么小程序的方案应该怎么去实现呢？

答案就是有 [page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html) 的情况下，优先使用它的 `page-style` 属性，进行 `css` 变量的切换

没有 `page-meta` 页面属性配置节点的情况下，我们只能通过配置单个 `view` 组件的样式变量，来进行主题色的切换

<!-- ## 目前小程序存在的限制

首先，小程序中是没有 `:root/html` 选择器的，取而代之的是 `page` 标签选择器，因为小程序中 `page` 才是每个页面的根节点。

其次小程序本身都是多页面的，而我们经常写的 `vue/react` 等等`spa`应用都是单页应用(可以做多页，我只是举个大多数的情况，不要钻牛角尖哈)。

而且 `web` 中我们可以通过 `element.style.setProperty` 这样的 `js api` 轻而易举的修改 `css` 变量的值，但是小程序不行，

我们以微信小程序中选取 `wxml` 的 `api`: `wx.createSelectorQuery` 为例，它甚至都无法选中 `page` 标签，更何况即使选中了，目前也没有能力动态的通过 `js api` 的方式去设置`css` 变量的值。

那么我们究竟应该怎么设计方案呢？ -->

## 方案的设计和实现

切换多主题主要依赖 `css` 变量切换，所以我们只要依照这个设计去实现即可

### 1. 页面属性配置节点 page-meta

利用 `page-meta` 页面属性配置节点的 `page-style` 属性，来进行 `css` 变量的切换

另外我们也可以通过 `page-meta` 组件的，来切换一些原生的样式

[page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html)

### 2. 自己实现 css 变量切换组件

首先既然我们无法利用**根**节点的变量切换来达成效果，但是我们可以通过组件的特性，即数据的响应式和插槽来达成效果。

我们可以设计一个 `ConfigProvider` 组件，它拥有一个`dom`节点，内部是一个插槽

其中那个`dom`节点就是我们主题相关变量寄居在的节点，而这个组件往往会作为一个根组件，在每个页面中被使用，去包裹我们真正的业务页面

甚至我们可以再设计一个 `BaseLayout` 这样的组件，去包含每个页面公共的部分，再在其中去引用 `ConfigProvider`，然后做一层插槽的透传即可。

#### 实现

> 这里我以 `vue` 的语法作为示例，因为我个人认为它比 `react` 和 `原生` 更容易让新手看懂

`ConfigProvider`的实现：

```html
<template>
  <view :class="[mode]" :style="styleObj">
    <slot></slot>
  </view>
</template>

<script lang="ts">

// import store from '@/store'
export default defineComponent({
  props: {
    vars: {
      type: [Object]
    },
    mode: {
      type: [String] as PropType<'light' | 'dark'>,
      default: 'light' // 这里你可以使用 store.state.mode 这样的值来获取用户的配置
    }
  },
  setup(props) {
    const styleObj = computed(() => {
      return Object.assign({}, props.vars)
    })
    return {
      styleObj
    }
  }
})
</script>
```

其中，`mode` 这个 `prop` 用来模拟实现了 `<html data-theme="<theme>" class="<theme>"></html>` 的效果，而 `vars` 则用来模拟实现 `js api` 设置 `css` 变量的效果。

通过这 `2` 个 `props`，你既可以通过 `mode` 的切换，把多个主题以及对应的变量值全部给写在你自己的 `css`中，然后通过切换`mode`，触发样式的覆盖来切换主题，这种是为静态的切换。

又可以通过设置 `vars`的值去动态的覆盖和切换，比如从服务端获取`css`变量的值，然后`set`进组件中，这显然是非常灵活的，这种是为动态的切换。

现在有了这个组件，我们就可以用它去包裹每一个页面了。

然后下一步，自然是要我们的页面和组件，都去应用那些我们设计的 `css` 变量了。

这一块可以参考下方链接中的`动态调整系统主题色(4)`中的`CssVar`方案，里面也有和 `tailwindcss` 相结合的部分，也欢迎阅读`动态调整web系统主题` 系列文章，并与在下进行探讨。

## 动态调整主题参考链接

1. [动态调整web系统主题? 看这一篇就够了](https://icebreaker.top/articles/2021/12/18-flexible-theme)
2. [动态调整web主题(2) 萃取篇](https://icebreaker.top/articles/2022/1/15-custom-theme-2)
3. [动态调整web主题(3): 基于tailwindcss插件的主题色生成方案](https://icebreaker.top/articles/2022/9/26-custom-theme-3)
4. [动态调整系统主题色(4): CssVar 与 Variant 方案的探索](https://icebreaker.top/articles/2023/10/5-custom-theme-4)

## 参考示例

微信上搜索 `tailwind`（未交 `30` 元个人资质费用，已无法搜索），进入小程序即可，小程序码：

![tailwind](./frameworks/img/tailwind-mp-qrcode.jpg)

实现源代码详见: [weapp-tailwindcss/tailwindcss-weapp](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/tailwindcss-weapp)

---

## 构建以及引入外部组件


## 前言

我们在日常的开发中，经常会去使用和封装各种各样的组件库。有些是开源的，第三方开发的UI库，有些是我们开发人员给自己的特定的业务封装的UI库。其中很多情况其实是以流行的 `开源UI库(或者fork的改版)` + `自己封装的业务组件为主的`

`开源UI库` 它们的样式相对来说是独立于整套系统的，比如它们的样式都是 `ant-`，`el-` 开头的，一般引入之后不会和原先系统里的样式产生冲突。而 `自己封装的业务组件`，由于往往和系统高度绑定也没有这样的问题。

那么如何用 `tailwindcss` 来构建/发布和引入自己封装的业务组件呢？

## 构建组件

### 核心思想

首先我必须重点把本篇文章的核心思想预先抛出：

`tailwindcss` 只是一个`css`生成器，它只是帮你按照一定的规则，从你的源代码中匹配字符串去生成`css`。所以在用它去构建组件的时候，一定要去思考你用 `tailwindcss` 生成的 `css` 的影响范围，因为大部分用 `tailwindcss` 都是默认全局应用的。但是你在组件里面的自定义样式很多情况下，是没有必要的。

根据这个核心思想，我们就可以知道在封装组件时可行和不可行的方式了，大致如下:

### 可行方案

1. `custom css selector` + `Functions & Directives`
2. `add prefix` (添加前缀)
3. `add scoped` (像 `vue` 的 `scoped` 一样添加 data-v-[hash] 类似的自定义属性，然后去修改css选择器)
4. 不打包方案 (不构建产物，直接发布，然后在项目里安装，再提取 `node_modules` 里制定的文本重新生成。)

### 不可行方案

1. module css 这会去修改 css 选择器。

## 可行方案详解

这里我写了2个`demo`分别是 `react` 和 `vue`，其中下方代码以 `vue` 为示例，`react`示例见下方的 `构建demo链接`

### custom css selector + Functions & Directives

这种方案其实非常的传统，仅仅使用到了 `tailwindcss` 中 `@apply` 和 `theme` 等等指令的功能。

比如我们有个组件 `ApplyButton.vue`，它的模板，样式和独立的 `tailwind.config.js` 分别如下所示:

```html
<script setup lang="ts">
</script>

<template>
  <button class="apply-button">ApplyButton</button>
</template>

<style src="./index.css"></style>
```

```css
@config 'tailwind.config.js';
@tailwind utilities;

.apply-button {
  @apply text-white p-4 rounded;
  background-color: theme("colors.sky.600")
}
```

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  content: [path.resolve(__dirname, './index.vue')],
  // ...
}
```

然后在打包的时候，以这个文件或者导出文件(`index.ts`) 为打包入口即可。

这样它的产物css中，选择器由于是你自己定义的，就能尽可能保证它是独一无二的。

它对应的`css`产物为:

```css
.apply-button {
  border-radius: 0.25rem;
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
  padding: 1rem;
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### add prefix

这个也很好理解，前缀嘛，各个UI库都是这样搞的，我们就可以创建出以下的代码:

```html
<script setup lang="ts">
</script>

<template>
  <button class="ice-bg-sky-600 ice-text-white ice-p-4 ice-rounded">PrefixButton</button>
</template>

<style>
@config 'tailwind.config.js';
@tailwind utilities;
</style>
```

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  prefix: 'ice-',
  content: [path.resolve(__dirname, './index.vue')],
}
```

它对应的`css`产物为:

```css
.ice-rounded {
  border-radius: 0.25rem;
}
.ice-bg-sky-600 {
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.ice-p-4 {
  padding: 1rem;
}
.ice-text-white {
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### add scoped

这个就是通过同时添加html标签属性和修改css选择器来做的了:

```html
<script setup lang="ts">
</script>

<template>
  <button class="bg-sky-600 text-white p-4 rounded">ScopedButton</button>
</template>

<style scoped>
@config 'tailwind.config.js';
@tailwind utilities;
</style>
```

这里仅仅给 `style` 加了一个 `scoped` 属性

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  content: [path.resolve(__dirname, './index.vue')],
}
```

`css` 生成结果为:

```css
.rounded[data-v-10205a53] {
  border-radius: 0.25rem;
}
.bg-sky-600[data-v-10205a53] {
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.p-4[data-v-10205a53] {
  padding: 1rem;
}
.text-white[data-v-10205a53] {
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### 不打包

以上三种方式总结一下，都是通过在选择器上下功夫来制作组件库的，而且它们都有一个打包的过程，即 `src`->`dist` 然后发布 `dist`

可是这第四种方案就不怎么一样了: 核心就是 `不打包`

即我们写好组件之后，直接把 `npm`的入口文件，指向 `src` ，然后直接把里面的组件发布(比如直接发布 `vue`组件)

这种情况下，你需要让你在 `node_modules` 里的组件再次经受一遍 `js` 的处理，比如 `vue sfc compiler`,`babel`,`swc`等等。

同时你也需要配置你项目里的 `tailwind.config.js` 去提取你 `node_modules` 里的组件源代码内容:

```diff
module.exports = {
  content: [
    './index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+   './node_modules/mypkg/src/components/**/*.{html,js,ts,jsx,tsx,vue}'
  ]
}
```

这样才能重新提取生成 `css` 在项目主`css chunk`里。

## 构建demo链接

<https://github.com/sonofmagic/weapp-tailwindcss/tree/main/how-to-build-components-by-tailwindcss>

## 相关 issues

<https://github.com/sonofmagic/weapp-tailwindcss/issues/247>

---

## CSS 单位转化


## rem 转 rpx (或 px)

在 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx) 章节，我们做了 `CSS` 中 `rem` 转化成 `px` / `rpx` 的方式。

但是除了 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx)，我们可能也有 `px 转 rpx` 的需求，这种情况实际上也很容易就能做到。

## px 转 rpx

### 4.3.0 以后

从 `weapp-tailwindcss@4.3.0` 开始，我们内置了 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件，提供了开箱即用的 `px` 转 `rpx` 的方式。

只需传入配置项:

```js
// vite

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  px2rpx: true
})
// webpack
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
new UnifiedWebpackPluginV5({
  // ...other-options
  px2rpx: true
})
```

只需传入一个 `true`，你写的所有的 `px` 都会被 `1:1` 的转换成 `rpx`，比如 `10px` -> `10rpx`

当然这个选项也可以传入一个 `object`, 这个默认值和参数，可以参考 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件。

如果希望 `px` 按 `1:2` 转换成 `rpx`（例如 `10px` -> `20rpx`），可以传入下面配置：

```js
// vite

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  px2rpx: {
    designWidth: 375,
    deviceRatio: {
      375: 2,
    },
  },
})
```

### 4.3.0 以前

这里我们使用 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 这个 `postcss` 插件来做。

> [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 由京东团队出品，应该是目前质量最高的 `px` 转 `rpx` 插件，而且已经被内置在了 `tarojs` 框架内

#### 安装插件

```bash npm2yarn
npm i -D postcss-pxtransform
```

#### 注册到 postcss 配置中

```js title="postcss.config.js"
module.exports = {
  plugins: {
    'tailwindcss': {},
    'autoprefixer': {},
    // highlight-start
    // 下方为 px 转 rpx 区域
    'postcss-pxtransform': {
      platform: 'weapp',
      // 根据你的设计稿宽度进行配置
      // 可以传入一个 function
      // designWidth (input) {
      //   if (input.file.replace(/\\+/g, '/').indexOf('@nutui/nutui-taro') > -1) {
      //     return 375
      //   }
      //   return 750
      // },
      designWidth: 750, // 可以设置为 375 等等来应用下方的规则,
      deviceRatio: {
        640: 2.34 / 2,
        // 此时应用到的规则，代表 1px = 1rpx
        750: 1,
        828: 1.81 / 2,
        // 假如你把 designWidth 设置成 375 则使用这条规则 1px = 2rpx
        375: 2 / 1,
      },
    },
    // highlight-end
  },
}

```

这样就能进行转化了，此时假如你写 `w-[20px]` 这种 `class` 它最终生效的样式会经过 `postcss-pxtransform` 转化，转变为 `width: 20rpx`, 当然这取决于你传入插件的配置，比如设计稿宽度 (`designWidth`)

你可以在 [taro 官网的设计稿及尺寸单位章节内](https://docs.taro.zone/docs/size) 查看这个插件的所有用法。

另外，假如你要禁止单个文件 `px` 转 `rpx`，可以在样式表文件内头部，添加 `/*postcss-pxtransform disable*/` 这样的注视，禁用该文件 `px` 转 `rpx`。

## 多单位转 px（unitsToPx）

在 `uni-app x` 等官方推荐使用 `px` 的场景，可以启用 `unitsToPx`，把 `rem/em/vw/vh/vmin/vmax/rpx` 等单位转换为 `px`。默认关闭。

```js
// vite

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  unitsToPx: true,
})
```

```js
// webpack
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
new UnifiedWebpackPluginV5({
  // ...other-options
  unitsToPx: {
    unitPrecision: 2,
    unitMap: {
      rem: 16,
      rpx: 0.5,
      vw: 3.75,
    },
  },
})
```

启用后（默认单位表）：
- `1rem` → `16px`
- `2rpx` → `1px`

> 注意：如果同时开启 `px2rpx` / `rem2rpx`，`unitsToPx` 会先转换成 `px`，后续还会继续转成 `rpx`。如果希望最终输出为 `px`，请不要同时开启 `px2rpx` / `rem2rpx`。

---

## Nodejs API


> 版本 2.11.0+ , 此为高阶 `api`，使用起来有难度，不适合新手，假如你不清楚你在做什么，请使用 `webpack/vite/gulp` 插件

有时候,我们不一定会使用 `webpack/vite/gulp`，可能是直接使用 `nodejs` 去构建应用，或者封装更高阶的工具，这时候可以使用`api`去转义你的应用。

## 如何使用

```js
// mjs or

// cjs
const { createContext } = require('weapp-tailwindcss/core')

async function main(){
  // createContext 可传入参数，类型为 UserDefinedOptions
  const ctx = createContext()
  // 3.1.0 开始 api 都是异步的，为 rust 工具链做准备
  const wxssCode = await ctx.transformWxss(rawWxssCode)
  const wxmlCode = await ctx.transformWxml(rawWxmlCode)
  const jsCode = await ctx.transformJs(rawJsCode)
  // 传入参数和输出结果均为 字符串 string

  // 然后你就可以根据结果去复写你的文件了
}

main()
```

:::tip
有一点要特别注意，在使用 `ctx.transformJs` 的时候，一定要确保 `tailwindcss` 已经执行完毕了！也就是说对应的 `postcss` 执行完毕。

因为 `js` 的转义依赖 `tailwindcss` 的执行结果，然后根据它，再去从你的代码中找到 `tailwindcss` 提取出的字符串，再进行处理的。

假如此时 `tailwindcss` 还没有执行，则插件就只能获取到一个 **空的** 提取字符串集合，这就无法进行匹配，从而导致你写在 `js` 里的类名转义失效。

比如这种情况:

```js
// index.js
const classNames = ['mb-[1.5rem]']
```

另外使用此种方式，编译缓存需要自行处理，且暂时没有类名的压缩与混淆功能
:::

---

## uni-app HbuilderX 使用方式

# uni-app HBuilderX 使用方式

:::caution
本文同时包含两条 `HBuilderX` 路线：

- `HBuilderX Vue3 Vite`：推荐
- `HBuilderX Vue2 Webpack`：仅供存量项目维护
:::

## HBuilderX Vue3 Vite（推荐）

> 配置会稍微复杂一些，这里推荐直接使用或者参考模板: [uni-app-vue3-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template) 或者 [若依移动端 (Gitee 地址)](https://gitee.com/sonofmagic/RuoYi-App)

### tailwind.config.js

注意: 在使用 `hbuilderx` 进行开发时，由于目录结构和启动项的不同，你必须要给你 `tailwind.config.js` 传入**绝对路径**:

```js title="tailwind.config.js"
const path = require("path");

const resolve = (p) => {
  return path.resolve(__dirname, p);
};
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 注意此处，一定要 `path.resolve` 一下, 传入绝对路径
  // 你要有其他目录，比如 components，也必须在这里，添加一下
  content: ["./index.html", "./pages/**/*.{html,js,ts,jsx,tsx,vue}"].map(resolve),
  // ...
  corePlugins: {
    // 跨多端可以 h5 开启，小程序关闭
    preflight: false,
  },
};
```

### vite.config.[tj]s

另外使用 `vite.config.[tj]s` 中注册 `tailwindcss` 时，也要传入绝对路径:

```js title="vite.config.[tj]s"

// 注意： 打包成 h5 和 app 都不需要开启插件配置
const isH5 = process.env.UNI_PLATFORM === "h5";
const isApp = process.env.UNI_PLATFORM === "app";
const WeappTailwindcssDisabled = isH5 || isApp;

const resolve = (p) => {
  return path.resolve(__dirname, p);
};

export default defineConfig({
  plugins: [
    uni(),
    uvwt({
      rem2rpx: true,
      disabled: WeappTailwindcssDisabled,
      // 由于 hbuilderx 会改变 process.cwd 所以这里必须传入当前目录的绝对路径
      tailwindcssBasedir: __dirname
    })
  ],
  css: {
    postcss: {
      plugins: [
        require("tailwindcss")({
          // 注意此处，手动传入你 `tailwind.config.js` 的绝对路径
          config: resolve("./tailwind.config.js"),
        }),
        require("autoprefixer"),
      ],
    },
  },
});
```

`hbuilderx` 正式版本的 `vue2` 项目,由于使用 `webpack4` 和 `postcss7`，所以只能使用本插件的 `weapp-tailwindcss/webpack4` 版本， 详见[uni-app-vue2-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-hbuilder-template)

或者下方也有一种 `Hack hbuilderx vue2 Way` 来在 `hbuilderx` `vue2` 项目中，使用 `webpack5` 和 `postcss8`

<!-- 另外出于开发体验的角度，还是推荐使用 `vscode` 作为你的开发工具，`hbuilderx` 只用于进行原生发布调试与 `ucloud` 部署用。 -->

## HBuilderX 与 uni-app cli 环境汇总

首先，你需要知道你的项目究竟使用的是什么打包工具，截止今天 `2023/12/18` 目前如下所示:

|                  | webpack  | vite | postcss  |
| ---------------- | -------- | ---- | -------- |
| hbuilderx vue2   | webpack4 | x    | postcss7 |
| uni-app cli vue2 | webpack5 | x    | postcss8 |
| hbuilderx vue3   | x        | √    | postcss8 |
| uni-app cli vue3 | x        | √    | postcss8 |

也就是说，目前 `hbuilderx vue2` 的项目是最老的，无法使用最新版本的 `tailwindcss`，其他都可以使用。

## HBuilderX Vue2 Webpack（存量项目） {#hbuilderx-vue2-webpack}

如果你实在必须在 `hbuilderx vue2` 的项目中使用 `tailwindcss`，那么你可以使用下面的方法来使用 `tailwindcss`

详见 [uni-app-vue2-tailwind-hbuilder-template](https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template)

## Hack hbuilderx vue2 Way

:::caution
以下方式为全局 Hack, 可能会在 `hbuilderx` 升级后出现问题
:::

`hbuilderx` 和 `hbuilderx alpha` 新建的 `vue2` 项目，发现它们的 `webpack` 版本被锁死在了 **`4`** ，我又用 `cli` 创建了一个 `vue2` 项目，发现已经是 `webpack5` 了，看起来只有 `cli` 创建的项目，会被默认升级 `webpack5`。

当然这并不意味着 `hbuilderx` 创建的 `vue2` 项目无法使用最新的这个插件，我们可以强行升级 `HBuilderX/plugins/uniapp-cli` 中的依赖，使得它适配 `webpack5`

> Macos uniapp-cli 路径在 /Applications/HBuilderX.app/Contents/HBuilderX/plugins/uniapp-cli
>
> Windows 的路径应该也在类似的地方，记得要先下载 vue2 的编译器，这个文件夹才有

来到 `uniapp-cli` 这个项目路径，执行 `yarn upgradeInteractive --latest` 升级项目依赖，重点升级 `@vue/cli-*` 相关包到 `5`

这时候 `webpack` 已经被升级到 `5` 版本了，然后你升级其他的 `loader` 到适配 `webpack5` 的版本(通常是最新版本)

再安装 `postcss` 和 `postcss-loader` 的最新版本，这时候你就把整个 `uni-app vue2` 项目的 `hbuilderx` 内置 `cli` 从 `webpack4`,`postcss7`变为了 `webpack5`,`postcss8` 了

不过代价是什么呢？那就是，这项改动是全局的！

你要想恢复设置，那只有重新安装 `uni-app vue2` 编译插件，或者重新安装整个 `hbuilderx`，所以这里还是推荐使用 `cli` 方式去创建项目，保证一个项目一个编译模式，你要节省空间就用 `pnpm`, 想用什么版本编译就用什么版本。

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=411561123&bvid=BV1EV41197Ps&cid=1413438914&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## mpx (原生增强)


<ExternalClassesReminder framework="mpx" />

在 `vue.config.js` 中注册：

```js title="vue.config.js"
const { defineConfig } = require('@vue/cli-service')
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')

module.exports = defineConfig({
  // other options
  configureWebpack(config) {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
      })
    )
  }
})

```

## 引入 Tailwind CSS 样式

Tailwind 的底层样式需要显式导入。不同主版本的包结构略有差异：

### Tailwind CSS v3.x

仍然可以直接引用 Tailwind 提供的底层样式文件（带 `.css` 扩展名）：

```html title="src/app.mpx"
<style lang="scss">
  @import 'tailwindcss/base.css';
  @import 'tailwindcss/components.css';
  @import 'tailwindcss/utilities.css';
</style>
```

### Tailwind CSS v4.x

v4 官方改用了全新的 CSS 包结构，推荐直接引入 `weapp-tailwindcss` 提供的聚合样式文件：

```html title="src/app.mpx"
<style lang="scss">
  @import 'weapp-tailwindcss/index.css';
</style>
```

这样即可获得预置的 base / components / utilities，同时避免 `postcss-import` 误解析到 JS 入口导致构建报错。

## mpx 中的 vscode tailwindcss 智能提示缺失设置

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `mpx` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置`

在 `include languages`,手动标记 `mpx` 的类型为 `html`

![如图所示](./img/vscode-tailwindcss.png)

保存设置，再去`mpx`文件里写`class`的时候，智能提示就出来啦。

---

## 原生开发(打包方案)


:::warning
注意！这是原生开发(**打包方案**)，假如你需要纯原生方案，请查看 [快速开始(纯原生)](/docs/quick-start/native/install)
:::

> 由于原生小程序没有 `webpack/vite/gulp` 工具链暴露出来，所以我们要添加这一套机制，来整个前端社区接轨，以此来实现更强大的功能。

:::tip
给原生小程序加入编译时这块 `webpack/vite/gulp` 等等工具，思路都是一样的，然而实现起来比较复杂，损耗精力，在此不提及原理。

更改模板工具链流程前，请确保你比较熟悉工具链开发（到我这样的水平就差不多了）。

另外这些模板，只需要稍微改一下产物后缀，添加 `tailwind.config.js` 的 `content` 就可以适配百度，头条，京东...各个平台。
:::

## gulp 模板

模板项目 [weapp-tailwindcss-gulp-template(gulp打包)](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/tree/main/demo/gulp-app)

## 组件样式的隔离性

:::tip
发现很多用户，在使用原生开发的时候，经常会问，为什么样式不生效。

这可能有以下几个原因:

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

这时候可以使用:

```js
/* 组件 custom-component.js */
Component({
  options: {
    addGlobalClass: true,
  }
})
```

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

[微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)

:::

## vscode tailwindcss 智能提示设置

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `wxml` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

1. 安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)

2. 安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置`

在 `include languages`,手动标记 `wxml` 的类型为 `html`

![如图所示](./img/vscode-setting.png)

智能提示就出来了:

![智能提示](./img/wxml-i.png)

---

## Rax (react)


在根目录下创建一个 `build.plugin.js` 文件，然后在 `build.json` 中注册：

```json title="build.json"
{
  "plugins": [
    "./build.plugin.js"
  ],
}
```

回到 `build.plugin.js`

```js title="build.plugin.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
module.exports = ({ context, onGetWebpackConfig }) => {
  onGetWebpackConfig((config) => {
    config.plugin('UnifiedWebpackPluginV5').use(UnifiedWebpackPluginV5, [
      {
        rem2rpx: true,
      },
    ]);
  });
};

```

---

## Taro (所有框架)


目前 Taro v4 同时支持了 `Webpack` 和 `Vite` 进行打包编译，`weapp-tailwindcss` 这 `2` 者都支持，但是配置有些许的不同

:::caution
假如你写了 `tailwindcss` 工具类不生效，可能是由于微信开发者工具默认开启了 `代码自动热重载` 功能，关闭它即可生效。

假如你和 `NutUI` 一起使用，或者启用了 `@tarojs/plugin-html` 插件，请一定要查看这个[注意事项](/docs/issues/use-with-nutui)!

<!-- 有群友遇到了转义特殊字符失败，之后变成了空格的文件，结果 `node_modules` 删了重新安装就好了。 -->

:::

下列配置同时支持 `taro` 的 `react` / `preact` / `vue2` / `vue3` 所有框架

## 使用 Webpack 作为打包工具

### 注册插件

在项目的配置文件 `config/index` 中注册:

```js title="config/index.[jt]s"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
// 假如你使用 ts 配置，则使用下方 import 的写法
// import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss/webpack'

{
  // 找到 mini 这个配置
  mini: {
    // postcss: { /*...*/ },
    // 中的 webpackChain, 通常紧挨着 postcss
    webpackChain(chain, webpack) {
      // 复制这块区域到你的配置代码中 region start
      // highlight-start
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              // 这里可以传参数
              rem2rpx: true,
            }]
          }
        }
      })
      // highlight-end
      // region end
    }
  }
}
```

然后正常运行项目即可，相关的配置可以参考模板 [taro-react-tailwind-vscode-template](https://github.com/sonofmagic/taro-react-tailwind-vscode-template)

:::info
`weapp-tailwindcss/webpack` 对应的插件 `UnifiedWebpackPluginV5` 对应 `webpack@5`

`weapp-tailwindcss/webpack4` 对应的插件 `UnifiedWebpackPluginV4` 对应 `webpack@4`

在使用 `Taro` 时，检查一下 `config/index` 文件的配置项 `compiler`，来确认你的 `webpack` 版本，推荐使用 `'webpack5'`

另外假如你使用了 [`taro-plugin-compiler-optimization`](https://www.npmjs.com/package/taro-plugin-compiler-optimization) 记得把它干掉。因为和它一起使用时，它会使整个打包结果变得混乱。详见 [issues/123](https://github.com/sonofmagic/weapp-tailwindcss/issues/123) [issues/131](https://github.com/sonofmagic/weapp-tailwindcss/issues/131)

<!-- 还有不要和 `terser-webpack-plugin` 一起注册使用，这会导致转义功能失效 详见 [**常见问题**](/docs/issues#taro-webpack5-环境下这个插件和-terser-webpack-plugin-一起使用会导致插件转义功能失效) 和 [issues/142](https://github.com/sonofmagic/weapp-tailwindcss/issues/142) -->

还有 `taro` 的 `prebundle` 功能老是出错，最近更新之后，由于 `prebundle` 默认开启，有时候连 `taro cli` 初始化的模板项目都跑不起来，假如遇到问题找不到原因，可以尝试关闭这个配置。

<!--
**另外不要开启二次编译缓存!**

```js
// 禁止二次编译缓存
cache: {
  enable: false
},
```

开启它会导致二次编译时，直接跳过插件的转义。另外还有一个 -->

<!-- `taro` 开发时热更新的问题，开发中保存 `tailwind.config.js` 文件，触发热更新会导致所有样式挂掉，此时重新保存任意 `jsx/tsx` 文件恢复正常。 -->

:::

## 使用 Vite 作为打包工具

:::danger
`Taro Vite` 目前整体稳定性较差，已知问题和样式链路 bug 较多，而且相关版本长期没有明显更新，不推荐在新项目里使用。

如果你没有强依赖 `Taro Vite`，优先选择 `Taro Webpack`、`uni-app`、`weapp-vite` 等更稳定的方案。
:::

由于 `taro@4` 的 `vite` 版本，目前加载 `postcss.config.js` 配置是失效的，所以我们目前暂时只能使用内联 `postcss` 插件的写法

### 在 `config/index.ts` 中注册插件

```ts title="config/index.[jt]s"

const baseConfig: UserConfigExport<'vite'> = {
  // ... 其他配置
  // highlight-start
  compiler: {
    type: 'vite',
    vitePlugins: [
      {
        // 通过 vite 插件加载 postcss,
        name: 'postcss-config-loader-plugin',
        config(config) {
          // 加载 tailwindcss
          if (typeof config.css?.postcss === 'object') {
            config.css?.postcss.plugins?.unshift(tailwindcss())
          }
        },
      },
      uvtw({
        // rem转rpx
        rem2rpx: true,
        // 除了小程序这些，其他平台都 disable
        disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'harmony' || process.env.TARO_ENV === 'rn',
        // 由于 taro vite 默认会移除所有的 tailwindcss css 变量，所以一定要开启这个配置，进行css 变量的重新注入
        injectAdditionalCssVarScope: true,
      })
    ] as Plugin[] // 从 vite 引入 type, 为了智能提示
  },
  // highlight-end
  // ... 其他配置
}
```

`tailwindcss` 即可注册成功，正常使用了

这段代码的意思为，在 `vite` 里注册 `postcss` 插件和 `vite` 插件

> `vite.config.ts` 只有在运行小程序的时候才会加载，`h5` 不会，所以只能通过这种方式进行 `小程序` + `h5` 双端兼容
> 但 `Taro Vite` 当前仍然不稳定，这部分内容仅作为历史方案和排障参考，不建议作为新项目默认选型。
> 如果你使用的是 `Taro Vite` + `tailwindcss@4`，更推荐在样式入口里直接写 `@import "weapp-tailwindcss/index.css";`，而不是依赖 `rewriteCssImports` 去把 `@import "tailwindcss";` 二次改写。这样排查样式链路会更直接。

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=966499437&bvid=BV1UW4y1w7VM&cid=1411385502&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## uni-app cli vue3 vite


:::warning
这是 `uni-app cli` 创建的项目的注册方式，如果你使用 `HbuilderX`，应该查看 [uni-app HbuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx)
:::

## 注册插件

创建完成后，快速上手中的准备工作都完成之后，就可以便捷的注册了：

```js title="vite.config.[jt]s"

export default defineConfig({
  // uni 是 uni-app 官方插件， uvtw 一定要放在 uni 后，对生成文件进行处理
  plugins: [uni(),uvwt()],
  css: {
    postcss: {
      plugins: [
        // require('tailwindcss')() 和 require('tailwindcss') 等价的，表示什么参数都不传，如果你想传入参数
        // require('tailwindcss')({} <- 这个是postcss插件参数)
        require('tailwindcss'),
        require('autoprefixer')
      ],
    },
  },
});

```

这里只列举了插件的注册，包括`postcss`配置完整的注册方式，参考配置项文件链接: <https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template>

## `tailwind.config` 扫描范围提醒

### 问题现象

如果你的 `uni-app` 项目把第三方插件或依赖放进了 `src/uni_modules`，同时又在 `tailwind.config` 中直接扫描整个 `src/**/*.{html,js,ts,jsx,tsx,vue}`，Tailwind v3 可能会把依赖源码里的正则表达式、README 示例文本误识别为 class，最终生成异常 CSS。

在小程序产物中，可能会看到类似：

```css
._ba-zA-Z_c__B {
  a-z-a--z:;
}
```

### 根因

这不是业务代码真的写了这样的类名，而是 Tailwind v3 的内容提取器误扫了 `src/uni_modules` 里的第三方源码或文档。

### 推荐配置

```ts title="tailwind.config.ts"
export default {
  content: [
    './index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
    '!./src/uni_modules/**/*',
  ],
}
```

### 最佳实践

- `content` 只扫业务源码，不要无差别扫整个 `src`
- 默认排除 `uni_modules`、`node_modules`、`dist`、`unpackage`
- 如果必须包含某个 `uni_modules` 包，只精确包含其中真正承载模板类名的文件

## 创建项目参考

`uni-app vite` 版本是 `uni-app` 最新的升级，它使用 `vue3` 的语法。

你可以通过 `cli` 命令创建项目 ([参考官网文档](https://uniapp.dcloud.net.cn/quickstart-cli.html)):

- 创建以 javascript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板）

```bash
npx degit dcloudio/uni-preset-vue#vite my-vue3-project
```

- 创建以 typescript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板）

```bash
npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project
```

> gitee 地址见上方的 `参考官网文档` 链接，点击跳转到 uni-app 官网即可

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=326378691&bvid=BV14w411773C&cid=1409199088&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## 🔥 uni-app x


目前 `weapp-tailwindcss` 从 `4.2.0` 版本开始，插件已经支持 `uni-app-x` 同时构建包括 `web`,`小程序`, `安卓`,`IOS`,`鸿蒙` 五端项目

:::warning 能力边界
`uvue` 原生 App 端不要依赖 `gap`、`gap-x-*`、`gap-y-*`，这些布局能力当前都不支持。

`space-x-*`、`space-y-*` 也不要在 `uni-app x` 中使用。请直接改用子项显式 `mt-*` / `ml-*`，或封装固定结构的间距组件。
:::

## 创建工具类

在项目中创建 `shared.js` 文件，用于存放一些工具函数：

```js title="shared.js"
const path = require('node:path')

function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = {
  r,
}
```

## 注册插件

创建 `vite.config.ts` 文件，注册插件：

> 这里特别注意 `uniAppX` 是从 `weapp-tailwindcss/presets` 这个预设中导出的

```js title="vite.config.[jt]s"

export default defineConfig({
    plugins: [
        uni(),
        UnifiedViteWeappTailwindcssPlugin(
            uniAppX({
                base: __dirname,
                rem2rpx: true,
            }),
        ),
    ],
    css: {
        postcss: {
            plugins: [
                tailwindcss({
                    config: r('./tailwind.config.js'),
                }),
            ]
        }
    }
});
```

## 更改 tailwindcss 配置

使用绝对路径，包括所有的提取文件

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}') 
  ],
  corePlugins: {
    preflight: false,
  },
}

```

## 现成模板可以直接使用或者参考

https://github.com/icebreaker-template/uni-app-x-hbuilderx

使用方式详见项目中的 `README.md`

---

## uni-app cli vue2 webpack


:::caution
这条 `uni-app cli vue2 webpack` 路线已经不推荐，仓库中的对应 classic demo 也已经移除。

新项目请直接使用 [uni-app cli vue3 vite](/docs/quick-start/frameworks/uni-app-vite)。
:::

<ExternalClassesReminder framework="uni-app" />

:::warning
本文仅作为存量项目归档说明保留，不再作为推荐接入方式。
:::

```js title="vue.config.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
/**
 * @type {import('@vue/cli-service').ProjectOptions}
 */
const config = {
  // some option...
  // highlight-start
  configureWebpack: (config) => {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
      })
    )
  }
  // highlight-end
  // other option...
}

module.exports = config
```

这样所有的配置便完成了！赶紧启动你的项目试试吧！

---

## tailwindcss 多上下文与独立分包


你看过动漫《百兽王》吗？《百兽王》的主人公是五个飞行员，他们分别驾驶黑、红、青、黄、绿五头机器狮，它们平时可以单独进行作战，遇到强敌时，也能进行五狮合体，成为巨大机器人“百兽王”。

同样，在日常开发中，我们经常遇到这样的问题，一个很大的程序，它有很多个独立的部分组成，每一个部分可以单独运行，也有独立的入口，相互之间没有任何的依赖，但是它们在同一个项目/任务里进行构建。

在这种场景下，去使用 `tailwindcss` 就往往需要去创建多个上下文，让这些上下文各自去管理我们程序中的指定的一块区域。

当然我写到这，相信大家也啥都没看懂，于是我搬出一个小程序中，独立分包的示例，来让大家理解这种思想。

## 什么是独立分包

独立分包是小程序中一种特殊类型的分包，可以独立于主包和其他分包运行。从独立分包中页面进入小程序时，不需要下载主包。当用户进入普通分包或主包内页面时，主包才会被下载。

独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。独立分包中插件、自定义组件的处理方式同普通分包。此外，使用独立分包时要注意：

1. 独立分包中不能依赖主包和其他分包中的内容，包括 js 文件、template、wxss、自定义组件、插件等（使用 分包异步化 时 js 文件、自定义组件、插件不受此条限制）
2. 主包中的 `app.wxss` 对独立分包无效，应避免在独立分包页面中使用 `app.wxss` 中的样式；
3. App 只能在主包内定义，独立分包中不能定义 App，会造成无法预期的行为；
4. 独立分包中暂时不支持使用插件。

> 更多信息详见 [微信独立分包官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/independent.html)

---

这里要特别注意第二条: **主包中的 `app.wxss` 对独立分包是无效的!!!**

在我之前提供的`tailwindcss`小程序模板的示例中，所有 `tailwindcss` 生成的 `wxss` 工具类都是在主包里共用的 (`app.wxss`)，这在大部分情况下运转良好，然而这在独立分包场景下，是不行的！因为主包的样式无法影响到独立分包。

那么应该怎么做才能解决这个问题呢？

## 创建与配置示例

这里笔者先以 `taro@3.6.7` 和 `weapp-tailwindcss@2.5.2` 版本的项目作为示例。

首先配置好 `weapp-tailwindcss` 的配置，然后在 `config/index.js` 中关闭 `prebundle` 功能，因为这在独立分包场景下会报一些未知的错误:

```js
const config = {
  compiler: {
    prebundle: {
      enable: false,
    },
    type: 'webpack5'
  },
  // .....
}
```

其次关闭插件对 `tailwindcss css var` 主块的寻址行为：

```js
chain.merge({
  plugin: {
    install: {
      plugin: UnifiedWebpackPluginV5,
      args: [{
        // 方法1: 不要传 appType
        // 注释掉 appType : 'taro'
        // 或者方法2: 让所有css chunk 都是 main chunk
        // mainCssChunkMatcher: ()=> true
        // 2 种选其一即可
      }]
    }
  }
})
```

接下来我们就可以创建一个独立分包 `moduleA`，在里面新建一个 `"pages/index"` 页面，并写入一个只属于 `moduleA` 的独一无二的 `tailwindcss class`，然后在 `app.config.ts` 里注册它:

```js
  subpackages: [
    {
      root: "moduleA",
      pages: [
        "pages/index",
      ],
      // 下方这个标志位，声明独立分包
      independent: true
    },
  ]
```

到这里，准备工作就完成了，接下来就可以设计方案了。

## 单 `tailwindcss` 上下文的方案（不完美不推荐）

这个方案是一个不完美的方案，在这里写出来是为了促进大家对 `tailwindcss` 的理解。

首先在独立分包中，也创建一个 `index.scss` 内容为:

```css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
```

然后在所有独立分包中的页面引用它，这样打包之后，独立分包里的 `tailwindcss` 样式也就生效了。

然而这种方式有一个巨大的问题，就是它会带来严重的 `css` 冗余。

因为此时 `tailwindcss` 上下文有且仅有一个，它会把在这个项目中，所有提取出来的 `css` 工具类，全部注入到所有的 `@tailwind` 指令里去。`@import 'tailwindcss/utilities'` 这个引入(本质实际上是`@tailwind`指令)一下子膨胀了起来。

这导致了，主包里的 `app.wxss` 里，会包含主包里所有的 `class` + 独立分包里所有的 `class`，而独立分包里的 `index.scss` 里，也包含主包里所有的 `class` + 独立分包里所有的 `class`!

这显然是不可接受的，因为主包是没有必要包含独立分包的 `class`，而独立分包里，也没有必要包含主包里的 `class`! 这只会白白增大打包后`wxss`文件的体积。

所以这个方案需要改进!

## 多 `tailwindcss` 上下文的方案

由于上面那个方案的问题，我们开始改进，就必须要创建多个 `tailwindcss` 上下文。

那么第一步就是要 **`↓`**

### 创建多个 `tailwind.config.js`

比如说我们只有一个独立分包，所以我们创建了2个 `tailwind.config.js`:

1. `tailwind.config.js` 用于主包以及相互依赖的子包
2. `tailwind.config.sub.js` 用于 `moduleA` 这个独立分包

内容如下:

#### 独立分包的上下文配置

```js
// `moduleA` 这个独立分包的 tailwind.config.sub.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 这里只提取 moduleA 这个独立分包下的文件内容
  content: ["./src/moduleA/**/*.{html,js,ts,jsx,tsx}"],
  // ....
  corePlugins: {
    preflight: false
  }
}
```

#### 主包以及相互依赖的子包的上下文配置

```js
// 主包以及相互依赖的子包的 tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // https://github.com/mrmlnc/fast-glob
  // 这里需要限定范围，不去提取 moduleA 这个独立分包下的文件内容
  // 所以后面跟了一个 `!` 开头的路径
  content: [
    "./src/**/*.{html,js,ts,jsx,tsx}",
    // 不提取独立分包里的 class
    "!./src/moduleA/**/*.{html,js,ts,jsx,tsx}"],
  // ....
  corePlugins: {
    preflight: false
  }
}
```

这样 `2` 个配置文件创建好了，接下来就要通过配置让它们各自在打包中生效。

### `postcss.config.js` 配置

这是非常重要的一块配置，我们需要把 `postcss.config.js` 的配置变成一个函数，这样才能把构建时的上下文传入进来：

```js
const path = require('path')

module.exports = function config(loaderContext) {
  // moduleA 下面的所有 scss 文件，都是独立模块的，应用不同的 tailwindcss 配置
  const isModuleA = /moduleA[/\\](?:\w+[/\\])*\w+\.scss$/.test(
    loaderContext.file
  )
  // 多个独立子包同理，加条件分支即可
  if (isModuleA) {
    return {
      plugins: {
        tailwindcss: {
          config: path.resolve(__dirname, 'tailwind.config.sub.js')
        },
        autoprefixer: {},
      }
    }
  }

  return {
    plugins: {
      // 不传默认取 tailwind.config.js
      tailwindcss: {},
      autoprefixer: {},
    }
  }
}
```

通过这种方式，我们成功的创建了 `2` 个不同的 `tailwindcss` 上下文，此时你进行打包之后，会发现

主包里的 `app.wxss` 和独立分包里的 `index.wxss`，里面的内容就已经各归各了，不再相互包含了。

## 尾言

当然，上面只是一种方案，达到这样的目的方式有很多种，比如你可以在运行时去修改 `postcss-loader` 对它进行劫持，或者拆成多个项目，分开构建。

我这篇文章只是抛砖引玉，相信聪明的你们一定可以举一反三的。

## 参考示例

示例见:<https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/taro-app>

---

## 1. 安装与配置 tailwindcss


> 推荐使用 `nodejs` 版本 `^20.19.0 || >=22.12.0`。目前低于 `18` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。
>
> 假如你安装的 `nodejs` 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 `--ignore-engines` 参数进行 `nodejs` 版本的忽略 。

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

这里我们参考 `tailwindcss` 官网中 `postcss` 的使用方式进行安装 ([参考链接](https://tailwindcss.com/docs/installation/using-postcss))

## 1. 使用包管理器安装 `tailwindcss`

```bash npm2yarn
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 tailwind.config.js 文件
npx tailwindcss init
```

:::info
`tailwindcss` 最新版本(`3.x`)对应的 `postcss` 大版本为 `8`，假如你使用像 `uni-app` 或 `taro` 这样的跨端框架，大概率已经内置了 `postcss` 和 `autoprefixer`
:::

## 2. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss`

> 注意：这只是比较普遍的注册方式，各个框架很有可能是不同的! 比如 `uni-app vue3 vite` 项目就必须要内联注册 `postcss` 选项! 详见下方的注意事项

```js title="postcss.config.js"
// 假如你使用的框架/工具不支持 postcss.config.js 配置文件，则可以使用内联的写法
module.exports = {
  plugins: {
    tailwindcss: {},
    // 假如框架已经内置了 `autoprefixer`，可以去除下一行
    autoprefixer: {},
  }
}
```

:::tip 注意事项
`uni-app vite vue3` 项目，必须在`vite.config.ts` 文件中，使用 `postcss` 内联的写法注册插件。相关写法可以参考我的这个模板项目: [uni-app-vite-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template)。

`uni-app vue2 / webpack` 属于存量项目路线，不再推荐新项目继续使用。
:::

## 3. 配置 `tailwind.config.js`

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

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 这里给出了一份 uni-app /taro 通用示例，具体要根据你自己项目的目录结构进行配置
  // 不在 content 包括的文件内，你编写的 class，是不会生成对应的css工具类的
  content: [
    './public/index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
    '!./src/uni_modules/**/*',
  ],
  // 其他配置项
  // ...
  corePlugins: {
    // 小程序不需要 preflight，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它
    preflight: false
  }
}
```

### `content` 扫描范围排障

#### 问题现象

在 `uni-app + tailwindcss@3` 场景下，如果项目把第三方插件或依赖放在 `src/uni_modules` 下，同时 `tailwind.config.js` 里使用了这类过宽配置：

```js
content: ['./src/**/*.{html,js,ts,jsx,tsx,vue}']
```

Tailwind 可能会扫描到依赖源码中的正则片段、README 示例文本或构建产物，例如 `[a-zA-Z:_]`，并把它误识别成 arbitrary property class。到了小程序产物阶段，再经过 `weapp-tailwindcss` 转译后，可能出现类似：

```css
._ba-zA-Z_c__B {
  a-z-a--z:;
}
```

这样的异常 CSS。

#### 根因

根因不是业务代码真的写了这个 class，而是 `tailwindcss@3` 默认内容提取器误扫了第三方目录中的源码、文档或构建产物。

#### 推荐配置

对于 `uni-app + tailwindcss@3`，请显式排除 `src/uni_modules`：

```ts title="tailwind.config.ts"
export default {
  content: [
    './index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
    '!./src/uni_modules/**/*',
  ],
}
```

如果你使用的是 `tailwind.config.js`，同样保持这三段含义不变即可。

#### 最佳实践

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

## 4. 引入 `tailwindcss`

在你的项目入口引入 `tailwindcss` 使它在小程序全局生效

### uni-app

比如 `uni-app` 的 `App.vue` 文件:

```html title="App.vue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
/* 使用 scss */
/* @import 'tailwindcss/base'; */
/* @import 'tailwindcss/utilities'; */
/* @import 'tailwindcss/components'; */
</style>
```

:::warning

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

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

:::

### Taro

又或者 `Taro` 的 `app.scss` 文件:

```scss title="app.scss"
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

// sass 版本1.25+ 使用 @use
// @use 'tailwindcss/base';
// @use 'tailwindcss/components';
// @use 'tailwindcss/utilities';

// 非 scss 的纯 css 文件，下列写法也是可以生效的
// @tailwind base;
// @tailwind components;
// @tailwind utilities;
```

然后在 `app.ts` 里引入这个样式文件即可。

这样 `tailwindcss` 的安装与配置就完成了，接下来让我们进入第二个环节：安装 `weapp-tailwindcss`。

## 参考链接

[`tailwindcss` 官方配置项](https://tailwindcss.com/docs/configuration)

---

## IDE 智能提示设置


## VS Code

> 首先，确保你已经安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

### 让 `Tailwind CSS IntelliSense` 识别 weapp-tailwindcss v4

`tailwindcss-intellisense` 在 v4 中必须看到 `@import "tailwindcss"` 才会将工作区视为 Tailwind 根文件。从 v4.7.10 起，`weapp-tailwindcss` 默认会在构建阶段把这些 `@import 'tailwindcss'` 自动改写成 `@import 'weapp-tailwindcss/index.css'`（可通过 `rewriteCssImports: false` 关闭）。这意味着你可以直接在 IntelliSense 辅助入口写 `@import 'tailwindcss';` 以获得智能提示，而插件会在最早的 PostCSS 流程中替换成小程序可用的样式。

如果仍希望与源码解耦，也可以使用 CLI 为 VS Code 生成一个仅供扩展使用的辅助 CSS：

```bash npm2yarn
npx weapp-tailwindcss vscode-entry --css src/app.css
```

- 默认输出在 `.vscode/weapp-tailwindcss.intellisense.css`，其中包含 `@import 'tailwindcss';`、常见的 `@source` globs 以及你传入的 CSS 入口（例如 `src/app.css`）。
- 该文件只用于激活 IntelliSense，不需要、也不应该被打包流程引用。
- 若需自定义文件名或额外的 `@source`，可通过 `--output`、`--source`、`--force` 等参数调整，运行 `npx weapp-tailwindcss vscode-entry --help` 查看全部选项。
- 如果不想生成独立文件，可以直接在真实入口写 `@import 'tailwindcss';`，默认启用的 `rewriteCssImports` 会让 webpack/vite 在 CSS 解析阶段把它映射到 `weapp-tailwindcss/index.css`（只影响样式导入，JS/TS `import 'tailwindcss'` 不会被修改）。

保存/重载任意文件后 VS Code 会检测到该辅助文件，从而让 `@import 'weapp-tailwindcss/index.css';` 的项目享受到完整的补全、悬浮和跳转体验。

如果你希望显式告诉 `Tailwind CSS IntelliSense`“某个 CSS 根文件对应哪些源码目录”，可以继续补充 `tailwindCSS.experimental.configFile`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.experimental.configFile": {
    ".vscode/weapp-tailwindcss.intellisense.css": "src/**"
  }
}
```

- 键名是给 `Tailwind CSS IntelliSense` 使用的 CSS 入口文件路径，它通常需要包含 `@import "tailwindcss";`。
- 键值是这个入口生效的源码范围，支持 glob；上面的配置表示，当你编辑 `src/**` 下的文件时，扩展会使用 `.vscode/weapp-tailwindcss.intellisense.css` 作为 Tailwind 根文件。
- 在 monorepo 或一个工作区里有多个 Tailwind 入口时，这种写法比“让扩展自动猜测”更稳定，也适合配合 `npx weapp-tailwindcss vscode-entry` 生成的辅助 CSS 一起使用。

### wxml 的智能提示

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `wxml` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)

然后下方提供了 `2` 种方式, `全局设置` 和 `工作区设置`, 根据你的需求仍选其一即可

#### 全局设置

点击 `vscode` 左下角的设置图标里，通过搜索关键词 `tailwindcss` ，找到 `Tailwind CSS IntelliSense` 插件的 `扩展设置`

在 `include languages`,手动标记 `wxml` 的类型为 `html`

![如图所示](./frameworks/img/vscode-setting.png)

智能提示就出来了:

![智能提示](./frameworks/img/wxml-i.png)

#### 工作区设置

在你的打开的工作区目录的根目录里，创建 `.vscode` 文件夹，然后添加 `settings.json` 内容如下:

```json
{
  "tailwindCSS.includeLanguages": {
    "wxml": "html"
  }
}
```

这样就通过你工作区的 `vscode` 设置，去覆盖了你全局的 `vscode` 设置，也能够达到上图中的效果。

### js,jsx,ts,tsx,vue...这类文件的智能提示

#### 场景

在安装配置好插件后，我们在写代码时，写到那些标签中的 `class=`,`className=`，这种场景时，智能提示一下子就可以出来。

然而我们在写 `js` 代码的时候，很多时候是直接在代码里，去写 `tailwindcss` 字符串字面量，比如:

```jsx
const clsName = 'bg-[#123456] text-[#654321]'

return 
```

写这种字符串是没有任何的智能提示的，怎么办呢？

#### 解决方案

这里给出一种基于插件的解决方案：

1. 安装 `clsx`:

```bash npm2yarn
npm i clsx
```

2. 进入你的 `vscode` 设置的 [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings)

在里面加入下方的配置:

```json
{
  "tailwindCSS.experimental.classRegex": [
    [
      "clsx\\(([^)]*)\\)",
      "(?:'|\"|`)([^']*)(?:'|\"|`)"
    ]
  ]
}
```

这样配置之后，智能提示就出来了:

![智能提示](./frameworks/img/js-intelliSense.png)

[Refer link](https://github.com/lukeed/clsx#tailwind-support)

#### 存在问题

这种原理也是依赖正则匹配，即 `Tailwind CSS IntelliSense 插件` 匹配到了当前 `vscode` 活动的文本域中，存在着 `clsx()` 方法这个关键词，所以就把智能提示给注入进去。

所以你这样写就不会生效:

```js

const btn = AAA('')
```

另外，你可以依据这个特性，修改/添加 `"tailwindCSS.experimental.classRegex"` 里的正则，然后自行封装一个方法，用来进行 `tailwindcss` 的智能提示。

## WebStorm

> 和 `vscode` 方式类似，同样使用 `clsx` 函数

1. 确保你的版本大于等于 [WebStorm 2023.1](https://www.jetbrains.com/webstorm/whatsnew/#version-2023-1-tailwind-css-configuration)

2. 打开设置，前往 [Languages and Frameworks | Style Sheets | Tailwind CSS](https://www.jetbrains.com/help/webstorm/tailwind-css.html#ws_css_tailwind_configuration)

3. 添加以下的配置:

```json
{
  "experimental": {
    "classRegex": ["clsx\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  }
}
```

> 如果你使用 `class-variance-authority` 的 `cva` 函数，只需再添加 `"cva\\(([^)]*)\\)"` 正则即可。

## HbuilderX

<https://ext.dcloud.net.cn/plugin?id=8560>

---

## 1. 安装与配置 tailwindcss(Native)


## 前言

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

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

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

### 运行环境

推荐使用 `nodejs` 版本 `^20.19.0 || >=22.12.0`。目前低于 `16` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。

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

## 创建项目

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

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

![](/img/create-project.png)

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

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

## 0. 初始化 `package.json`

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

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

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

## 1. 使用包管理器安装 `tailwindcss`

然后执行:

```bash npm2yarn
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 tailwind.config.js 文件
npx tailwindcss init
```

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

## 2. 配置 `tailwind.config.js`

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

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

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

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

内容如下:

```js title="postcss.config.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` 并运行吧！

---

## 2. 安装这个插件并运行


## 安装插件

在项目目录下，执行:

```bash npm2yarn
npm i -D weapp-tailwindcss weapp-vite
```

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

## 执行初始化命令

在命令行中运行

```sh
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` 初始化命令之后，我们需要在项目里执行一下安装命令:

```bash npm2yarn
npm i
```

## 注册插件

给 `package.json` 添加下列脚本:
```json title="package.json"
{
  "scripts": {
    "postinstall": "weapp-tw patch"
  }
}

```

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

```ts title="vite.config.ts"

export default defineConfig({
  // highlight-start
  plugins: [
    uvwt({
      rem2rpx: true,
    }),
  ],
  // highlight-end
})

```

## 开始运行

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

使用 `npm run build` 进行构建

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

使用微信开发者工具，直接导入工程目录，然后即可预览效果！

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

## 配置好的模板

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

[weapp-vite-tailwindcss-template](https://github.com/weapp-vite/weapp-vite/tree/main/apps/weapp-vite-tailwindcss-template)

或者直接执行命令:

```bash npm2yarn
npx weapp-vite create my-app
```

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

{/* [vite-native](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/apps/vite-native) */}

{/* [native-weapp-tailwindcss-template](https://github.com/sonofmagic/native-weapp-tailwindcss-template) */}

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

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

这可能有以下几个原因:

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

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

```json title="custom-component.json"
{
  "styleIsolation": "apply-shared"
}
```

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

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

更多的文档详见: [微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)

:::

## 想了解更多 weapp-vite

更多场景和配置，请查看 [weapp-vite 文档网站](https://vite.icebreaker.top/)

---

## 4. rem 转 rpx (或 px)


> 此为可选步骤，根据你自己的需求进行配置。通常此配置的值，是由你拿到的设计稿尺寸决定的。

## 为什么要配置 rem 转 rpx 呢？

这是因为 `tailwindcss` 里面工具类的长度单位，默认都是 `rem`，比如:

```css
.m-4 {
  margin: 1rem;
}
.h-4 {
  height: 1rem;
}
/*......*/
```

`rem`这个单位在 `h5` 环境下自适应良好，但小程序环境下，我们大部分都是使用 `rpx` 这个 `wxss` 单位来进行自适应，所以就需要把默认的 `rem` 单位转化成 `rpx`。

## 三种转化方式(根据你的需求选其一即可)

## 插件内置 rem 转 rpx 功能 (推荐)

在 `^3.0.0` 版本中，所有插件都内置了 `rem2rpx` 参数，默认不开启，要启用它只需将它设置成 `true` 即可

```js
// vite.config.js

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  // highlight-next-line
  rem2rpx: true
})
// webpack
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
new UnifiedWebpackPluginV5({
  // ...other-options
  // highlight-next-line
  rem2rpx: true
})
```

设置为 `true` 相当于 `rem2rpx` 传入下方这样一个配置对象:

```js
{
  // 32 意味着 1rem = 16px = 32rpx
  rootValue: 32,
  // 默认所有属性都转化
  propList: ['*'],
  // 转化的单位,可以变成 px / rpx
  transformUnit: 'rpx'
}
```

:::tip
为什么 `rootValue` 默认值是 `32`?

这是因为开发微信小程序时, 设计师基本都使用 `iPhone6` 作为视觉稿的标准，此时 `1px = 2rpx`。

然后默认情况下 `1rem = 16px`，所以 `1rem = 16px = 32rpx`。

详见 [WXSS 尺寸单位](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html#%E5%B0%BA%E5%AF%B8%E5%8D%95%E4%BD%8D) 章节，
:::

当然你也可以自行传入一个 `object` 来进行更多配置，具体的配置项见 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel)

### 优势

这种方式 **最简单**，和插件集成度高，传入一个配置就好了。

## 外置 postcss 插件

<!-- 假如你想要把项目里，所有的 `rem` 都转化成 `rpx`，那么 `postcss plugin`: [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) 适合你。 -->

<!-- 推荐第一种转化方式，这会把项目里所有你编写的，或者引入的第三方控件里的 `rem` 单位，全部转化为 `rpx`，同时这个包也提供了各种配置项，帮助你进行更加细致的操作。 -->

首先我们安装 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel)

```bash npm2yarn
npm i -D postcss-rem-to-responsive-pixel
```

安装好之后，把它注册进你的 `postcss.config.js` 即可:

```js title="postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-rem-to-responsive-pixel': {
      // 32 意味着 1rem = 32rpx
      rootValue: 32,
      // 默认所有属性都转化
      propList: ['*'],
      // 转化的单位,可以变成 px / rpx
      transformUnit: 'rpx'
      // postcss-rem-to-responsive-pixel@6 版本添加了 disabled 参数，用来禁止插件的转化
      // disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'rn'
    }
  }
}
```

:::tip

一些用户在使用 `tarojs` 开发的时候，错误的把 `tailwindcss` 配置在了 `config/index.js` 的 `postcss` 里，导致不生效。

原因实际上是因为 `config/index.js` 的 `postcss`这个配置，只是用来配置 `tarojs` **内置** `postcss` 插件的参数。

要使用 `tailwindcss`，你需要在项目根目录，新建一个 `postcss.config.js`，然后把上面的代码写入进去。
:::

### 优势

这种方式 **最灵活**，你可以自由的决定 `postcss` 插件的加载顺序，也可以按你自己的策略按需加载插件 (比如特定目录下的样式才接受这个插件的转化)

## 外置 tailwindcss 插件

你想缩小一下范围，只把 `tailwindcss` 生成的工具类的单位，从 `rem` 转变为 `rpx`，那么我写的 `tailwindcss preset`: [tailwindcss-rem2px-preset](https://www.npmjs.com/package/tailwindcss-rem2px-preset) 适合你。

同样我们安装它：

```bash npm2yarn
npm i -D tailwindcss-rem2px-preset
```

然后在 `tailwind.config.js` 中，注册这个预设：

```js title="tailwind.config.js"
module.exports = {
  presets: [
    require('tailwindcss-rem2px-preset').createPreset({
      // 32 意味着 1rem = 32rpx
      fontSize: 32,
      // 转化的单位,可以变成 px / rpx
      unit: 'rpx'
    })
  ]
  // ...
}
```

这样即可完成 `tailwindcss` 默认工具类的 `rem` 转 `rpx` 的配置了。

### 优势

这种方式受影响范围 **最小**，因为 `preset` 方式处理 `tailwindcss`,不会把你写的其他样式里的 `rem` 转化成 `rpx`

## px 转 rpx

如果你也有 [`px 转 rpx`](/docs/quick-start/css-unit-transform) 的需求，你可以查看 [CSS 单位转化](/docs/quick-start/css-unit-transform) 这个章节。

---

## 2. 安装 weapp-tailwindcss


在项目目录下，执行:

```bash npm2yarn
npm i -D weapp-tailwindcss

# 假如 tailwindcss 在 weapp-tailwindcss 之后安装，可以手动执行一下 patch 方法
# npx weapp-tw patch
```

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

:::caution 使用 pnpm@10+
`pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。
:::

:::info
执行 `weapp-tw patch` 主要是做2件事情

### 1. 给当前你本地的 `tailwindcss` 打上支持 `rpx` 的补丁 (小程序特有单位，非 `web` 标准)。

否则你一旦使用像 `text-[14.43rpx]` 这样的任意值写法，生成出来的 `css` 样式就是 `color: 14.43rpx;`，显然是错误的。

它会被 `tailwindcss` 认为是一种颜色，从而导致生成错误，样式不生效。

详见 [rpx 任意值颜色或长度单位二义性与解决方案](/docs/issues/rpx-ambiguities)

### 2. 暴露 `tailwindcss` 运行上下文给 `webpack`/`vite`/`glup` 插件。

这样就能够在 `js` 中，和 `postcss` 插件进行通信，从而达到共享上下文的效果。

---

而添加上面一段 `npm scripts` 的用途是，利用 `npm hook`, 每次安装包后，都会自动执行一遍 `weapp-tw patch` 这个脚本。

这样即使 `tailwindcss` 更新了版本导致了补丁失效，也会在重新下载后，第一时间被打上。

如果你希望在补丁前“强制刷新 `tailwindcss-patch` 的缓存目录（如 `node_modules/.cache/tailwindcss-patch`）”，可以在命令后附加 `--clear-cache`：

```json title="package.json"
 "scripts": {
   "postinstall": "weapp-tw patch --clear-cache"
 }
```

默认不清理缓存，更加保守稳定；仅当怀疑缓存导致补丁未生效或版本不一致时再开启该参数。
:::

我们已经完成了这些步骤了，最后就是注册这个插件，到各个不同的框架里去，马上就好！

---

## uni-app 条件编译语法糖插件


> 版本需求 2.10.0+

## 这是什么玩意?

在 `uni-app` 里，存在一种类似宏指令的[样式条件编译写法](https://uniapp.dcloud.net.cn/tutorial/platform.html#%E6%A0%B7%E5%BC%8F%E7%9A%84%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91):

```css
/*  #ifdef  %PLATFORM%  */
平台特有样式
/*  #endif  */
```

> uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor)

在 `weapp-tailwindcss@2.10.0+` 版本中内置了一个 `css-macro` 功能，可以让你的 `tailwindcss` 自动生成带有条件编译的样式代码，来辅助你进行多平台的适配开发，效果类似如下方式:

```html
<!-- 默认 -->
<view class="ifdef-[H5||MP-WEIXIN]:bg-blue-400">Web和微信小程序平台蓝色背景</view>
<view class="ifndef-[MP-WEIXIN]:bg-red-500">非MP-WEIXIN平台红色背景</view>
<view class="ifdef-[MP-WEIXIN]:bg-blue-500 ifndef-[MP-WEIXIN]:bg-red-500">微信小程序为蓝色，不是微信小程序为红色<view>
<!-- 自定义 -->
<view class="wx:bg-blue-400 -wx:bg-red-400">微信小程序为蓝色，不是微信小程序为红色</view>
<view class="tt:bg-blue-400">头条小程序蓝色</view>
```

或者这样的条件样式代码:

```css
/*只在 H5 和 MP-WEIXIN, 背景为蓝色，否则为红色 */
.apply-test-0 {
  @apply ifdef-[H5||MP-WEIXIN]:bg-blue-400 ifndef-[H5||MP-WEIXIN]:bg-red-400;
}
/* 自定义 */
.apply-test-1 {
  @apply mv:bg-blue-400 -mv:bg-red-400 wx:text-blue-400 -wx:text-red-400;
}
```

让我们看看如何使用吧！

## 如何使用

这里需要同时配置 `tailwindcss` 和 `postcss` 的配置文件才能起作用，其中 `tailwindcss` 配置修改的方式大体类似， `uni-app` `vue2/3` `postcss`插件的注册方式，有些许不同:

### tailwind.config.js 注册

首先在你的 `tailwind.config.js` 注册插件 `cssMacro`:

#### Tailwind CSS 3.x 配置

```js
const cssMacro = require('weapp-tailwindcss/css-macro');
/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */
    cssMacro(),
  ],
};
```

#### Tailwind CSS 4.x 配置

> v4 推荐直接在入口 CSS 中通过 `@plugin` 引入。

```css
/* tailwind.css */
@import "tailwindcss";
@plugin "weapp-tailwindcss/css-macro";

/* 可选：为常用平台创建语义别名 */
@utility platform-weixin:(value) {
  @apply ifdef-[MP-WEIXIN]:$(value);
}
@utility not-alipay:(value) {
  @apply ifndef-[MP-ALIPAY]:$(value);
}
```

若需要自定义更多静态变体，可额外保留一个 `tailwind.config.ts` 以传入参数：

```ts

export default {
  plugins: {
    cssMacro: cssMacro({
      variantsMap: {
        wx: 'MP-WEIXIN',
        '-wx': { value: 'MP-WEIXIN', negative: true },
      },
    }),
  },
}
```

> [!TIP]
> `cssMacro` 的动态变体（`ifdef:` / `ifndef:`）依赖 Tailwind 内置的 `matchVariant`，请确保 Tailwind 版本 ≥ 3.2；在 v4 中该 API 同样可用。

### postcss 插件注册

对应的 `postcss` 插件位置为 `weapp-tailwindcss/css-macro/postcss`

值得注意的是，你必须把这个插件，注册在 `tailwindcss` 之后和 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前。

> `@dcloudio/vue-cli-plugin-uni/packages/postcss` 为 vue2 cli项目特有，vue3不用管。

注册在 `tailwindcss` 之后很好理解，我们在针对 `tailwindcss` 的产物做修改，自然要在它执行之后处理，注册在 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前则是因为 `uni-app` 样式的条件编译，靠的就是它。假如在它之后去处理不久已经太晚了嘛。

> 这里提一下 postcss 插件的执行顺序，假如注册是数组，那就是按照顺序执行，如果是对象，那就是从上往下执行，详见[官方文档](https://www.npmjs.com/package/postcss-load-config#ordering)

#### uni-app vite vue3

```diff
// vite.config.ts 文件

// postcss 插件配置
const postcssPlugins = [require('autoprefixer')(), require('tailwindcss')()];
// ... 其他省略
+ postcssPlugins.push(require('weapp-tailwindcss/css-macro/postcss'));
// https://vitejs.dev/config/
export default defineConfig({
  plugins: vitePlugins,
  css: {
    postcss: {
      plugins: postcssPlugins,
    },
  },
});
```

> 可以参考这个项目的配置 [demo/uni-app-vue3-vite](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app-vue3-vite)

#### uni-app vue2

:::warning
`uni-app vue2 / webpack` 已经不推荐，仓库中的对应 classic demo 也已移除。

如果你仍在维护存量项目，可以继续按这个思路注册；新项目请直接参考 `demo/uni-app-vue3-vite`。
:::

vue2 cli 项目默认会带一个 `postcss.config.js`，我们直接在里面注册即可:

```diff
const webpack = require('webpack')
const config = {
  parser: require('postcss-comment'),
  plugins: [
    // ...
    require('tailwindcss')({ config: './tailwind.config.js' }),
    // ...
+   require('weapp-tailwindcss/css-macro/postcss'),
    require('autoprefixer')({
      remove: process.env.UNI_PLATFORM !== 'h5'
    }),
+   // 注意在 tailwindcss 之后和 这个之前
    require('@dcloudio/vue-cli-plugin-uni/packages/postcss')
  ]
}
if (webpack.version[0] > 4) {
  delete config.parser
}
module.exports = config
```

> 仓库已不再保留 `demo/uni-app`，新项目请参考 [demo/uni-app-vue3-vite](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app-vue3-vite)

### 配置完成

现在配置好了这2个地方，目前你就可以直接使用 `ifdef` 和 `ifndef` 的条件编译写法了！

```html
<!-- 默认 -->
<view class="ifdef-[H5||MP-WEIXIN]:bg-blue-400">Web和微信小程序平台蓝色背景</view>
<view class="ifndef-[MP-WEIXIN]:bg-red-500">非MP-WEIXIN平台红色背景</view>
<view class="ifdef-[MP-WEIXIN]:bg-blue-500 ifndef-[MP-WEIXIN]:bg-red-500">微信小程序为蓝色，不是微信小程序为红色<view>
<!-- 自定义 -->
<view class="wx:bg-blue-400 -wx:bg-red-400">微信小程序为蓝色，不是微信小程序为红色</view>
<view class="tt:bg-blue-400">头条小程序蓝色</view>
```

不过你肯定会觉得这种默认写法很烦！要写很多，不要紧，我还为你提供了自定义的方式，接下来来看看配置项吧！

## 配置项

这里提供了一份示例，

> uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor)

```js
const cssMacro = require('weapp-tailwindcss/css-macro');
/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */
    cssMacro({
      // 是否包含 ifdef 和 ifndef，默认为 true
      // dynamic: true,
      // 传入一个 variantsMap
      variantsMap: {
        // wx 对应的 %PLATFORM% 为 'MP-WEIXIN'
        // 有了这个配置，你就可以使用 wx:bg-red-300
        wx: 'MP-WEIXIN',
        // -wx，语义上为非微信
        // 那就传入一个 obj 把 negative 设置为 true
        // 就会编译出 ifndef 的指令
        // 有了这个配置，你就可以使用 -wx:bg-red-300
        '-wx': {
          value: 'MP-WEIXIN',
          negative: true
        },
        mv: {
          // 可以使用表达式
          value: 'H5 || MP-WEIXIN'
        },
        '-mv': {
          // 可以使用表达式
          value: 'H5 || MP-WEIXIN',
          negative: true
        }
      }
    }),
  ],
};
```

## IDE智能提示

只要你使用 `vscode`/`webstorm` 这类IDE，加上安装了 `tailwindcss` 的官方插件。

智能提示会根据你对 `cssMacro` 这个插件的配置，直接生成出来！

> 假如没有下方的智能提示出现，有可能是 `tailwindcss` 插件挂了，这时候可以改好配置之后 **重启** `vscode` 以重新运行插件

这里我们以上面 `配置项` 为例:

### 动态提示: ifdef-[] 和 ifndef-[]

![macro-tip0](./img/macro-tip0.png)

### 配置的静态提示: wx 和 -wx

![macro-tip1](./img/macro-tip1.png)

---

## Tailwindcss 2.x


目前，有些用户由于现有的项目，已经是 `webpack 4`, `postcss 7.x` 且无法往上升级，但是又想要使用 `tailwindcss`, 

所以写了这个文档作为参考，在现有版本的情况下，**不推荐**任何的新项目使用

## 安装

在这种条件下，只能使用 `tailwindcss 2.x` 版本。

参考 https://v2.tailwindcss.com/docs/installation#post-css-7-compatibility-build 中的安装方式

安装好之后，一定要打开 `jit` 模式, https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template/blob/master/tailwind.config.js

具体更多的细节，详见下方模板代码。

## vue2 hbuilderx 参考模板

注意，一定要在开发环境中设置 

```js
process.env.TAILWIND_MODE = "watch"
```

才能正常热更新

模板源代码地址:

https://github.com/icebreaker-template/uni-app-vue2-tailwind-hbuilder-template

---

## 初始化 package.json

## 1. 安装

```bash npm2yarn
# 初始化 package.json
npm init
# 安装包
npm install -D tailwindcss @tailwindcss/postcss weapp-tailwindcss
```

<Patch />

## 2. 添加 `vite.config.ts`

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      tailwindcssBasedir: __dirname,
      cssEntries: [
        // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
        path.resolve(__dirname, './src/app.css'),
      ],
    }),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss({
          base: __dirname
        })
      ]
    }
  }
});
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 3. 添加样式

<UniappHbuilderStyle/>

现在，在你的页面里面去随意的编写样式，比如 `bg-[#123456] text-[#654321]`, 然后运行到微信开发者工具即可

## 布局限制

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

## 参考模板

- [uni-app-x-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-x-hbuilderx) 

- [uni-app-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-hbuilderx-tailwindcss-v4)

---

## UniappCliStyle

在 `src/app.css` 中引入 `weapp-tailwindcss/index.css`，这个文件会作为 `cssEntries` 的入口：

```css title="src/app.css"
@import "weapp-tailwindcss/index.css";
```

<CssImportReminder />

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

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

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

```css title="src/main.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```

然后把 `experimental.configFile` 指向它：

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

这个 `src/main.css` 只用于 IntelliSense，不要在 `App.vue` 里实际引入。应用运行时仍然使用 `src/app.css` 里的 `@import "weapp-tailwindcss/index.css"`。

## `@source` 扫描范围排障

### 问题现象

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

### 根因

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

### 推荐配置

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

```css title="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"`。

:::warning

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

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

:::

---

## UniappHbuilderStyle

在 `src/app.css` 中引入 `weapp-tailwindcss/index.css`，这个文件会作为 `cssEntries` 的入口：

```css title="src/app.css"
@import "weapp-tailwindcss/index.css";
```

<CssImportReminder />

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

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

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

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

然后把 `experimental.configFile` 指向它：

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

这个 `src/main.css` 只用于 IntelliSense，不要在 `App.vue` / `App.uvue` 里实际引入。应用运行时仍然使用 `src/app.css` 里的 `@import "weapp-tailwindcss/index.css"`。

## `@source` 扫描范围排障

### 问题现象

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

### 根因

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

### 推荐配置

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

```css title="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 的候选集合。

:::warning

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

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

:::

---

## Mpx


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

更改 `mpx.config.js` 注册 `weapp-tailwindcss`

```js title="mpx.config.js"
const { defineConfig } = require('@vue/cli-service')
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
const tailwindPostcss = require('@tailwindcss/postcss')
module.exports = defineConfig({
  outputDir: `dist/${process.env.MPX_CURRENT_TARGET_MODE}`,
  pluginOptions: {
    mpx: {
      plugin: {
        postcssInlineConfig: {
          // tailwindcss@4 需要在此处注册 @tailwindcss/postcss，详见 templates/mpx-tailwindcss-v4/mpx.config.js
          ignoreConfigFile: true,
          plugins: [tailwindPostcss()]
        },
        srcMode: 'wx',
        hackResolveBuildDependencies: ({ files, resolveDependencies }) => {
          const path = require('path')
          const packageJSONPath = path.resolve('package.json')
          if (files.has(packageJSONPath)) files.delete(packageJSONPath)
          if (resolveDependencies.files.has(packageJSONPath)) {
            resolveDependencies.files.delete(packageJSONPath)
          }
        }
      },
      loader: {}
    }
  },
  configureWebpack(config) {
    // 添加的代码在这里
    // highlight-start
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        appType: 'mpx',
        rem2rpx: true,
        cssEntries: [
          // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
          path.resolve(__dirname, './src/app.css'),
        ],
      })
    )
    // highlight-end
  }
})
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
> tailwindcss@4 下必须在 `mpx.config.js` 里用 `postcssInlineConfig` 注册 `@tailwindcss/postcss`（同仓库 `templates/mpx-tailwindcss-v4/mpx.config.js` 的写法），否则插件不会生效，无需再单独维护 `postcss.config.js`。
> 这里的注册目标也必须是纯 `css` 入口文件，不要把 `tailwindcss@4` 放进 `scss` / `less` / `sass` 入口里，否则样式生成和 `weapp-tailwindcss` 转译都可能失效。

## 添加样式

在 `src/app.css` 中引入 `weapp-tailwindcss`：

```css title="src/app.css"
@import "weapp-tailwindcss/index.css";
```

<CssImportReminder />

> 💡 如果你希望在任意样式文件中直接引用包内样式，请使用 `@import "weapp-tailwindcss/index.css";`。这样可以确保 `postcss-import` 解析到的是真实的 CSS 资源，避免出现 "Unknown word "use strict"" 这一类由于误解析到 JS 文件导致的构建报错。

### Tailwind CSS 样式引用指引

- **Tailwind CSS v3.x**：沿用旧模块名即可（例如 `@import 'tailwindcss/base.css'`、`@import 'tailwindcss/components.css'`、`@import 'tailwindcss/utilities.css'`）。
- **Tailwind CSS v4.x**：推荐直接引入 `weapp-tailwindcss` 提供的聚合样式：

```html title="src/app.mpx"
<style lang="scss">
  @import 'weapp-tailwindcss/index.css';
</style>
```

这样可以一次性获得 base / components / utilities，并规避 `postcss-import` 误解析 JS 入口的报错。如果你是从 v3 升级，只需将原来的三个 `@import` 换成这条语句即可。

然后在项目目录下，小程序全局的 `app.mpx` 中，通过 `@import` 引入该文件：

```html title="app.mpx"
<style lang="css">
@import "./app.css";
</style>
```

更改好配置之后，直接启动即可

## 参考模版

https://github.com/icebreaker-template/mpx-tailwindcss-v4

---

## patch

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

:::caution 使用 pnpm@10+
`pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。
:::

这是为了给 `tailwindcss@4` 打上支持 `rpx` 单位的补丁，否则它会把 `rpx` 认为是一种颜色

如需在补丁前强制刷新 `tailwindcss-patch` 的缓存，可改为：

```json title="package.json"
 "scripts": {
   "postinstall": "weapp-tw patch --clear-cache"
 }
```

默认不清理缓存；只有当你怀疑缓存导致补丁未生效或目标不一致时，才需要添加 `--clear-cache`。***

---

## 开发参考手册


:::warning
由于 `tailwindcss@4.x` 本身还在快速的开发迭代中，即使是小版本也可能带有一些意外的 `Breaking Change`

所以以下内容可能会经常变更，如果发现已经过时，请提 `issue` 或者直接修复提 `pr`
:::

<!-- ## 出于兼容性考虑，请使用 `tailwindcss@3.x`

目前用户汇报了部分手机，可能是由于内部使用的 `webview` 版本太低，或者一些其他的因素，导致了样式不生效的问题，尤其是华为手机。

`tailwindcss@4.x` 生成的样式，对现代的浏览器来说刚刚好，可是对那些移动设备来说，就不一定了。 -->

所以假如你要兼容更多的手机机型，请使用 `tailwindcss@3.x`。

## 定位的变化: 样式预处理器

相对于 `tailwindcss@3` 版本， `tailwindcss@4` 存在定位的重大变更

它直接变成了一个样式预处理器，和原生 `css` 已经它的规范相结合，相辅相成。

所以你在 `4.x` 版本中，不应该让 `tailwindcss` 和 `sass`,`less`,`stylus` 一起使用

详见: https://tailwindcss.com/docs/compatibility#sass-less-and-stylus

## 集成选择

`tailwindcss` 集成上提供了多种选择 (`cli`,`vite`,`postcss`)，这里我们主要选择 `@tailwindcss/postcss`，原因如下:

1. `@tailwindcss/postcss` 兼容性更好，开发打包器使用 `vite` 和 `webpack` 的都能用，而 `@tailwindcss/vite` 这里只有 `vite` 能用。
2. `@tailwindcss/vite` 很容易和其他的 `vite` 插件起冲突，尤其是和 `uni-app` / `taro` 一起使用的时候，依赖注册的顺序和编译 `hook` 注册的顺序
3. `uni-app`/`taro` 这种框架，默认都是 `cjs` 加载的，而 `@tailwindcss/vite` 只提供了 `esm` 的版本，所以集成上可能会遇到问题
4. `tailwindcss@3.x` 是 `postcss` 插件，`@tailwindcss/postcss` 也是 `postcss` 插件，所以选择它，项目迁移升级的成本会更低。

所以，综合考虑下来，我们主要选择 `@tailwindcss/postcss`。

当然，你也完全可以使用 `uni-app vite vue3` + `@tailwindcss/vite` 这种组合。从编译速度出发, `@tailwindcss/vite` 会更快，但是可能需要一些额外的配置，行为也有可能和 `tailwindcss@3.x` 不一致。

## 小程序样式引入 `weapp-tailwindcss` 不同点

在小程序场景下，`tailwindcss@4` 的文档示例建议直接写成 `@import "weapp-tailwindcss/index.css"`，而不是继续使用 `@import "tailwindcss"` 再依赖 `rewriteCssImports` 做二次改写。

### 有什么区别?

`@import "weapp-tailwindcss/index.css"` 本质上会解析到 `weapp-tailwindcss` 提供的小程序适配入口。相比 `@import "tailwindcss"`，主要区别是:

1. `"weapp-tailwindcss"` 没有 `"tailwindcss"` 中 `h5` `preflight` 的类(这些都是给 `h5` 用的，小程序用不到)
2. `"weapp-tailwindcss"` 中，不使用 `tailwindcss` 默认的 `@layer` 来控制样式优先级。这是因为小程序本身不支持 `css` `@layer` 这个特性，强行启用会造成一些样式难以覆盖的问题。

### 多端开发

假如你需要进行多端的开发，那么可以使用对应框架的样式条件编译写法，比如 `uni-app`:

```css
/*  #ifdef  H5  */
@import "tailwindcss";
/*  #endif  */
/*  #ifndef  H5  */
@import "weapp-tailwindcss/index.css";
/*  #endif  */
```

详见 https://uniapp.dcloud.net.cn/tutorial/platform.html

## css 作为配置文件

由于在 `tailwindcss@4` 中，配置文件默认为一个 `css` 文件，所以你需要显式的告诉 `weapp-tailwindcss` 你的入口 `css` 文件的绝对路径。

来让 `weapp-tailwindcss` 和 `tailwindcss` 保持一致的处理模式

> `cssEntries` 为一个数组，就是你写 `@import "weapp-tailwindcss/index.css";` 的那些文件，可以有多个

```ts
{
  cssEntries: [
    // 就是你 @import "weapp-tailwindcss/index.css"; 那个文件
    // 比如 tarojs
    path.resolve(__dirname, '../src/app.css')
    // 比如 uni-app (没有 app.css 需要先创建，然后让 `main` 入口文件引入)
    // path.resolve(__dirname, './src/app.css')
  ],
}
```

假如不添加这个，会造成 `tailwindcss` 插件生成的样式，转义不了的问题。

:::warning 只注册到 CSS，不要注册到预处理样式文件
`tailwindcss@4` 的入口请只放在 `.css` 文件里，例如 `app.css`。

不要把 `@import "weapp-tailwindcss/index.css"`、`@tailwindcss/postcss`，或者对应的 `cssEntries` 指向 `scss`、`less`、`sass` 这类预处理样式文件，否则很容易导致最终样式生成失败，或者 `weapp-tailwindcss` 转译失效。

推荐做法是：

1. 新建一个纯 `css` 入口文件，例如 `src/app.css`
2. 只在这个 `css` 文件里写 `@import "weapp-tailwindcss/index.css";`
3. 再让业务里的 `scss` / `less` 去间接引用这个 `css`，或者由主入口文件引入它
:::

> 插件会自动根据已安装的 Tailwind 版本开启 v4 模式。只有在调试自定义 `tailwindcss` 目录或多版本共存时，才需要在 `tailwindcss` 配置里手动指定 `version`。

## 使用 @apply

如果你想在 页面或者组件独立的 `CSS` 模块中使用 `@apply` 或 `@variant`，你需要使用 `@reference` 指令，来导入主题变量、自定义工具和自定义变体，以使这些值在该上下文中可用。

```css
/* 到你引入 tailwindcss 的 css 相对路径 */
@reference "../../app.css";
/* 如果你只使用默认主题，没有自定义，你可以直接 reference tailwindcss */
@reference "tailwindcss";
```

详见: https://tailwindcss.com/docs/functions-and-directives#reference-directive

## @layer 在小程序的降级方案

`tailwindcss@4` 使用原生的 `@layer` 去控制样式的优先级

> 如果你不知道什么是 `@layer`，你可以阅读这篇文档 https://developer.mozilla.org/zh-CN/docs/Web/CSS/@layer

但是像 `uni-app` / `taro` 这种框架，默认都是直接引入很多内置样式的。

于是就会出现下方尴尬的情况: 优先级 `(0,1,0)` 的 `class` 选择器样式无法覆盖 `(0,0,1)` 的标签选择器样式:

![](./tailwindcss-v4-uniapp-layer.png)

这种情况，你就非常需要兼容性降级方案，即使用 [`postcss-preset-env`](https://www.npmjs.com/package/postcss-preset-env) (`weapp-tailwindcss` 已经内置了这个插件了，你可以直接使用它的配置，详见 [cssPresetEnv](/docs/api/options/important#csspresetenv))

这在开发需要兼容低版本移动端 h5 的时候很重要。

## 使用 pnpm

默认使用 `pnpm` 的时候，由于 `pnpm` 是无法使用幽灵依赖的

但是 `uni-app`/`taro` 出于一些历史原因，是需要幽灵依赖的，这时候可以在项目下创建 `.npmrc` 添加内容如下

```txt title=".npmrc"
shamefully-hoist=true
```

然后重新执行 `pnpm i` 安装包即可运行

## 智能提示

目前 `tailwindcss@4` 的 VS Code `Tailwind CSS IntelliSense` 插件，会优先从它识别到的 Tailwind 入口里推导配置与候选类名。

在小程序项目里，我们现在推荐直接写 `@import "weapp-tailwindcss/index.css";`。这样运行时和转译链路更直接，但当前插件自动扫描时并不会把它稳定识别为 Tailwind 4 的显式入口，所以经常出现智能提示失效。

相关修复可以关注这个 PR：

- https://github.com/tailwindlabs/tailwindcss-intellisense/pull/1557

根据 `tailwindcss-intellisense` 当前实现，真正生效的做法是显式配置 `tailwindCSS.experimental.configFile`。对于 `tailwindcss@4`，这里传入的不是 `tailwind.config.js`，而是你的 **CSS 入口文件**。

如果项目只有一个入口，直接把它指向实际在 `cssEntries` 里使用的那个 `app.css` 即可：

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

这样配置后，扩展会直接把 `src/app.css` 当成 Tailwind 4 项目入口来加载，即使它里面写的是 `@import "weapp-tailwindcss/index.css"`，也能恢复补全、悬浮提示和诊断。

如果你的项目有多个 Tailwind 入口，则改用对象写法，把每个 CSS 入口映射到对应的文件范围：

```json title=".vscode/settings.json"
{
  "tailwindCSS.experimental.configFile": {
    "packages/a/src/app.css": "packages/a/src/**",
    "packages/b/src/app.css": "packages/b/src/**"
  }
}
```

如果你仍然想额外创建一个只给编辑器使用的 CSS 文件，也必须把这个文件写进 `tailwindCSS.experimental.configFile`，仅仅在 `App.vue` 里引入它并不会让 IntelliSense 绑定到该入口。

下面是一个编辑器专用入口的可选写法：

```css title="main.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```

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

这个 `main.css` 只用于 IntelliSense，不需要也不应该在实际应用入口里引入。业务真正生效的入口仍然是你的 `app.css` 里的 `@import "weapp-tailwindcss/index.css"`。

这里必须使用 `@import "tailwindcss"`，而不是 `@import "weapp-tailwindcss/index.css"` 或 `@import "weapp-tailwindcss/theme.css"`。原因是 `tailwindcss-intellisense` 当前源码里，真正决定是否按 v4 设计系统加载的是 `packages/tailwindcss-language-server/src/util/v4/design-system.ts` 里的 `isMaybeV4()`，它只检查：

- `@import "tailwindcss"`
- `@theme {}`

也就是说：

- `@import "weapp-tailwindcss/index.css"`：不会触发这段 v4 识别
- `@import "weapp-tailwindcss/theme.css"`：同样不会触发
- `@import "tailwindcss"`：可以稳定触发 v4 IntelliSense

如果你的项目不是 `dist` 目录，而是 `unpackage`、`build` 等其他输出目录，请把 `@source not "dist";` 改成自己的实际产物目录。

## `uni-app` / `uni-app x` 项目里的 `@source` 扫描范围排障

### 问题现象

当 `uni-app` 项目把第三方插件或依赖放在 `src/uni_modules` 下，或者 `HBuilderX` / `uni-app x` 项目把依赖放在根目录 `uni_modules` 下时，如果 Tailwind 4 的 CSS 入口没有显式排除这些目录，扫描阶段就可能把依赖源码中的正则片段、README 示例文本或构建产物误识别为候选。

最终表现通常不是业务代码真的写了这些类名，而是产物里平白多出很多无意义样式，增加排查成本。

### 根因

根因和 Tailwind v3 的 `content` 误扫描一致，都是因为扫描范围过宽，把第三方源码、README 示例文本或构建产物误当成候选。

### 推荐配置

命令行 `uni-app` 项目推荐：

```css
@source not "../src/uni_modules";
```

`HBuilderX` / `uni-app x` 项目推荐：

```css
@source not "uni_modules";
```

同时保留对实际构建产物目录的排除，例如：

```css
@source not "dist";
```

或：

```css
@source not "unpackage";
```

### 最佳实践

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

> **注意**：从 `tailwindcss-intellisense` 的源码来看，`experimental.configFile` 在 v4 下支持 `string` 和 `object` 两种形式，路径会相对于工作区或 `.code-workspace` 文件解析。关键是“显式声明 CSS 入口”，并且这个入口本身要满足它的 v4 识别条件。

## 如何去除 preflight 样式

在引入 `@import "weapp-tailwindcss/index.css"` 时，默认会引入 `preflight` 样式。

### 什么是 preflight 样式

一些全局的 `reset` 样式，用来让一些标签行为统一的，比如你在你的样式中，看到的:

```css
view,text,::before,::after,::backdrop {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
  border: 0 solid;
}
```

类似这样的就是 `weapp-tailwindcss` 给你的应用注入的 `preflight` 样式

### 解决方案

`@import "weapp-tailwindcss/index.css"` 本质上由三个部分组成:

```css
@import 'weapp-tailwindcss/theme.css';
@import 'weapp-tailwindcss/preflight.css';
@import 'weapp-tailwindcss/utilities.css';
```

所以想要去除 `preflight` 样式，只需像下面一样写即可

```diff
- @import "weapp-tailwindcss/index.css";
+ @import 'weapp-tailwindcss/theme.css';
+ @import 'weapp-tailwindcss/utilities.css';
```

## 使用大写单位 (h-[100PX]) 无效问题

默认情况下，在 `process.env.NODE_ENV === 'production'` 的时候， `tailwindcss` 会自动进入优化模式

它会进行 `CSS` 单位的校准，比如把大写的 `PX` 转化为小写的 `px`，你要禁用这个行为可以这样传入。

```js
export default {
  plugins: {
    "@tailwindcss/postcss": {
      optimize: false
    },
  }
}
```

详见: [@tailwindcss/postcss](https://github.com/tailwindlabs/tailwindcss/blob/7779d3d080cae568c097e87b50e4a730f4f9592b/packages/%40tailwindcss-postcss/src/index.ts#L73C35-L73C72)

---

## Taro vite


:::danger
`Taro Vite` 目前不稳定，已知 bug 较多，而且依赖链版本较老，不推荐在新项目里使用。

如果没有强依赖，优先选择 `Taro Webpack`、`uni-app`、`weapp-vite` 等更稳定的方案。
:::

## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

> 这里不使用 `@tailwindcss/vite` 是由于 `taro` 配置没法加载纯 `esm` 不是 `cjs` 的包, 会爆错误 `No "exports" main defined`

<Patch />

## 配置

```js title="config/index.ts"

{
  compiler: {
    type: 'vite',
    vitePlugins: [
      {
        name: 'postcss-config-loader-plugin',
        config(config) {
          // 加载 tailwindcss
          if (typeof config.css?.postcss === 'object') {
            config.css?.postcss.plugins?.unshift(tailwindcss())
          }
        },
      },
      UnifiedViteWeappTailwindcssPlugin({
        rem2rpx: true,
        appType: 'taro',
        cssEntries: [
          // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
          path.resolve(__dirname, '../src/app.css'),
        ],
      }),
    ]
  },
}
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
> `cssEntries` 请指向 `.css` 文件，不要指向 `scss` / `less` / `sass`。`@import "weapp-tailwindcss/index.css"` 也只应写在纯 `css` 入口里，否则会导致样式生成或转译失效。

> 这里使用 `vite` 插件直接去加载 `tailwindcss`，这是由于 `taro4 vite` 不会自动去加载项目下的 `postcss.config.js`，所以只能定义这个 `postcss-config-loader-plugin`

## 添加样式

在项目目录下的 `src/app.css` 中，添加以下内容：

```css title="src/app.css"
@import "weapp-tailwindcss/index.css";
```

> 在 `Taro Vite` 场景下，文档示例统一直接写 `@import "weapp-tailwindcss/index.css";`，不再依赖 `rewriteCssImports` 把 `@import "tailwindcss";` 二次改写。这样配置链路更直接，排查样式问题时也更容易定位。

更改好配置之后，直接运行启动项目，微信开发者工具导入这个项目，即可看到效果。

> 再强调一次：这页内容更适合作为历史接入说明与排障参考，不建议把 `Taro Vite` 作为新的默认技术选型。

## 参考模板

https://github.com/icebreaker-template/taro-vite-tailwindcss-v4

---

## Taro webpack


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

### 在你的根目录创建 `postcss.config.mjs`

```js title="postcss.config.mjs"
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}
```

### 在你的 `app.css` 里面添加

```css
@import "weapp-tailwindcss/index.css";
```

<CssImportReminder />

### 注册插件

在项目的配置文件 `config/index` 中注册:

```js title="config/index.[jt]s"

// 假如你使用 js 配置，则使用下方 require 的写法
// const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
// const path = require('node:path')

{
  // 找到 mini 这个配置
  mini: {
    // postcss: { /*...*/ },
    // 中的 webpackChain, 通常紧挨着 postcss 
    webpackChain(chain, webpack) {
      // 复制这块区域到你的配置代码中 region start
      // highlight-start
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              // 这里可以传参数
              rem2rpx: true,
              cssEntries: [
                // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
                path.resolve(__dirname, '../src/app.css'),
              ],
            }],
          },
        },
      })
      // highlight-end
      // region end
    }
  }
}
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 运行

然后执行命令发布到微信小程序

```bash npm2yarn
npm run dev:weapp
```

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

## 参考模板

https://github.com/icebreaker-template/taro-webpack-tailwindcss-v4

---

## 高阶篇：性能、兼容与团队协作


Tailwind CSS 4 带来了更强大的原生语法，但在小程序环境中仍需平衡兼容性与团队协作。本篇从工程化视角出发，帮助你在真实项目中稳定地落地、优化与维护。

## 1. 处理 `@layer` 与兼容性

小程序运行时目前对 CSS Cascade Layers 支持有限，当你引用第三方组件或自定义样式时可能出现覆盖关系错乱。`weapp-tailwindcss` 内置的 `postcss-preset-env` 可将 `@layer` 转译成传统写法来提升兼容性。

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      cssEntries: [
        /* ... */
      ],
      cssPresetEnv: {
        stage: 1,
        features: {
          'cascade-layers': true,
        },
      },
    }),
  ],
})
```

> 如果你只在微信小程序调试，可使用开发者工具的「自定义编译」观察处理前后的差异；若仍存在覆盖问题，可结合传统的 `!important` 或布局拆分策略。

额外提示：

- `cssSelectorReplacement.root` 默认包含 `['page', '.tw-root', 'wx-root-portal-content']`。当页面外的容器（例如自定义 tab bar、弹出层根节点等）需要承载 Tailwind 注入的 `--tw-*` 变量时，只需在容器上加上 `class="tw-root"` 即可复用整套预设，无需额外配置。下面是一个在自定义 tab bar 中注入主题变量的示例：

  ```xml title="custom-tab-bar/index.mpx"
  <template>
    <view class="tw-root bg-[var(--tab-bar-bg)] text-[var(--tab-bar-color)]">
      <!-- 这里仍然可以继续使用 Tailwind 原子类 -->
    </view>
  </template>
  ```

  搭配 `cssPreflight` 注入的变量或自定义 `@theme`，可以把 tab bar 的主题色、渐变背景等统一交给 Tailwind 管理。若你需要覆盖其他容器名称，仍可以通过配置把 `cssSelectorReplacement.root` 扩展为更多选择器。

- `cssPresetEnv` 会参与最终构建，请在发布前执行一次 `pnpm build:apps` 或对应的 `pnpm build` 命令确认产物

## 2. 多端共存与按需构建

团队常同时维护小程序与 H5 版本，此时可以通过多个 `@source` 区分模板范围，并结合条件编译实现按需打包：

```css title="src/app.css"
@source "../src/**/*.{vue,wxml}";
@source not "../src/**/*.h5.*"; /* 排除只用于 H5 的模板 */

/* 多端开发：H5 用官方 tailwindcss，小程序用 weapp-tailwindcss */
/*  #ifdef  H5  */
@import "tailwindcss";
/*  #endif  */
/*  #ifndef  H5  */
@import "weapp-tailwindcss/index.css";
/*  #endif  */
```

当需要拆分体积时，可以把不同业务域的样式写到各自的 `entry.css`，再将路径加入 `cssEntries`：

```ts
UnifiedViteWeappTailwindcssPlugin({
  cssEntries: [
    path.resolve(import.meta.dirname, './src/app.css'),
    path.resolve(import.meta.dirname, './src/features/order/app.css'),
  ],
})
```

这样 Tailwind 只会为实际引用的模板生成原子类，避免冗余。

## 3. 产物体积与性能优化

- **控制扫描范围**：`@source` 支持 `not` 语法，排除 `dist`、`node_modules` 等目录能显著加快增量编译
- **合理使用自定义工具类**：把相同组合提炼成 `@utility`，既减少模板体积，也方便统一调整
- **按需开启 `rem2rpx` / `px2rpx`**：在仅小程序端需要 rpx 的情况下，可以在多端构建中动态开启
- **缓存管理**：Tailwind 会在 `.tailwind` 写入缓存。CI 环境可缓存该目录以提升构建速度，发布前若需彻底清理运行 `pnpm exec tailwindcss --config tailwind.config.js --clean` 或直接删除缓存目录

## 4. 调试与质量保障

- **可视化定位**：使用 `outline` 类临时标记组件边界，例如在调试时加上 `outline outline-1 outline-dashed outline-brand/60`
- **断言样式存在**：核心组件可引入快照测试或 DOM 断言，结合 Vitest + @testing-library 验证关键类名
- **lint 约束**：在 `eslint-plugin-tailwindcss` 或团队约定的 lint 规则中，限制自定义类名必须通过 `@utility`
- **回归验证**：Tailwind 升级时执行 `pnpm test`, `pnpm e2e` 确认核心链路稳定，同时在主流机型（尤其是低版本安卓）上真机预览

## 5. 升级与维护策略

1. **版本对齐**：Tailwind 4 迭代频繁，升级前先在 `CHANGELOG` 与 GitHub Release 查 Breaking Change，再在测试分支试跑。
2. **切分 Changeset**：对外发布库时遵循 [Changesets](https://github.com/changesets/changesets) 约定，确保依赖者知道何时需要手动介入。
3. **文档同步**：团队内部记录 `@utility`、`@theme` 的设计规范，推荐把核心样式写进 Storybook 或内部组件示例库。
4. **遇到问题及时回馈**：`weapp-tailwindcss` 社区对 Tailwind 4 的需求反馈快速，遇到兼容问题可通过 Issue 或 PR 参与共建。

至此，你已经掌握了 Tailwind CSS 4 在小程序中的完整落地思路：从环境搭建、组件实践到性能与协同。结合现有的框架集成文档，就能为新成员提供一套体系化的学习路径。

---

## 入门篇：快速认识 Tailwind CSS 4 与 weapp-tailwindcss


Tailwind CSS 4 重新定义了“原子化”样式的组织方式：配置文件换成了 `CSS`，主题变量与自定义工具也变成了原生语法。这一变化对小程序生态同样生效，`weapp-tailwindcss` 已经适配了新的编译流程。本篇入门指南帮助你在 30 分钟内从零搭好一套 `tailwindcss@4` + `weapp-tailwindcss` 的基础开发环境，并理解最核心的概念。

## 本篇能学到什么

- 搭建一套可运行的 Tailwind CSS 4 + 小程序项目骨架
- 分清核心配置（`cssEntries`、`@source`、`@reference` 等）各自负责的事情
- 理解 `@tailwindcss/postcss`、`@tailwindcss/vite` 与编译插件的差异
- 掌握验证样式是否生效的最小闭环，避免“写了没生效”的常见坑

如果你还未接触过 `weapp-tailwindcss`，建议先浏览 [新手快速上手（Tailwind CSS 3.x）](/docs/quick-start/install) 了解插件能解决的问题，再回来完成 4.x 的配置。

## 环境准备

| 名称 | 说明 |
| --- | --- |
| Node.js ≥ 18 | Tailwind CSS 4 要求更高的 Node 版本，建议使用 LTS 20 |
| pnpm ≥ 8 | Monorepo 与文档项目统一使用 `pnpm` |
| 小程序框架 | 任选 `weapp-vite`、`uni-app`、`taro` 等，推荐使用现成模板 |
| 代码编辑器 | VS Code 并安装 `Tailwind CSS IntelliSense` 插件 |

初始化项目后，执行一次 `pnpm install` 以及框架 CLI 的初始化命令（如 `pnpm create @tarojs/cli`）。随后即可进入 Tailwind CSS 配置步骤。

## 步骤一：安装依赖

在项目根目录执行：

```bash
pnpm add -D tailwindcss@latest @tailwindcss/postcss postcss weapp-tailwindcss
```

> `@tailwindcss/postcss` 兼容 Vite、Webpack、Rspack 等大多数构建链路；对于纯 Vite 项目也可以酌情改用 `@tailwindcss/vite`，但在小程序场景下 `postcss` 方案更稳定。

## 步骤二：注册 weapp-tailwindcss 插件

以 `weapp-vite` 为例（不同框架请对照对应的 [集成指南](/docs/quick-start/v4)）：

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      // 常用内置能力：开启 px 自动转换
      rem2rpx: true,
      cssEntries: [
        // 声明 Tailwind 的入口 CSS，必须是绝对路径
        path.resolve(import.meta.dirname, './src/app.css'),
      ],
    }),
  ],
})
```

`cssEntries` 对 `tailwindcss@4` 至关重要，它告诉 `weapp-tailwindcss` 哪些 CSS 需要参与编译与转义。漏掉该配置将导致产物中缺失样式。

## 步骤三：配置 PostCSS

```js title="postcss.config.js"
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

Tailwind CSS 4 已内置 Autoprefixer，无需手动补充。若项目仍需其他 PostCSS 插件，保持旧的写法即可。

## 步骤四：创建入口 CSS

在 `src/app.css` 中写入：

```css title="src/app.css"
@import "weapp-tailwindcss/index.css";

/* 声明模板扫描路径，确保原子类能被收集 */
@source "../src/**/*.{vue,tsx,jsx,svelte,wxml}";

/* 需要自定义设计令牌时可在此编写 */
@theme {
  --color-brand: oklch(67% 0.2 264);
  --spacing-safe: clamp(12px, 1.2vw + 8px, 24px);
}
```

<CssImportReminder />

`@source` 是 Tailwind 4 的新写法，用于替代旧版本的 `content` 配置。路径请根据项目结构调整。若你需要在局部样式文件使用 `@apply`，在对应文件顶部添加 `@reference "./app.css";`。

## 步骤五：验证类名是否生效

创建一个最小页面（以 `src/pages/index/index.vue` 为例）：

```html title="src/pages/index/index.vue"
<template>
  <view class="flex min-h-screen flex-col items-center justify-center bg-slate-50 px-6 py-safe">
    <view class="w-full max-w-md rounded-3xl bg-white p-6 shadow-lg shadow-slate-200">
      <text class="text-xs font-semibold uppercase tracking-[0.22em] text-slate-500">Tailwind CSS 4</text>
      <text class="mt-3 text-2xl font-bold text-slate-900">欢迎来到 weapp-tailwindcss</text>
      <text class="mt-2 text-sm leading-6 text-slate-600">
        现在可以尝试修改 <text class="font-medium text-brand">bg-brand</text> 或自定义 <text class="font-medium">utility</text>。
      </text>
      <button class="mt-6 inline-flex items-center justify-center rounded-xl bg-brand px-4 py-2 text-sm font-semibold text-white shadow transition hover:bg-brand/90 active:scale-95">
        开始实践
      </button>
    </view>
  </view>
</template>
```

> `py-safe` 是我们在上文 `@theme` 中声明的自定义变量（通过 `--spacing-safe` 导出），可验证主题自定义是否生效。

运行框架命令（如 `pnpm dev:weapp` 或 `pnpm run build -- --watch`），查看开发者工具中的页面是否渲染出预期样式。如果没有：

- 检查 `cssEntries` 是否指向了正确路径
- 确认 `@source` 是否包含当前文件扩展名
- 若在单文件组件内使用 `@apply`，确保添加了 `@reference`

## 常见下一步

- 阅读 [Tailwind CSS 4 官方文档](https://tailwindcss.com/docs/installation) 了解更多原生指令
- 针对不同框架的集成细节，请查阅「🧪Tailwind CSS @4.x」分类中的各篇文档
- 想理解 `@layer` 在小程序下的降级方案，可继续阅读本教程的 [进阶篇](/docs/quick-start/v4/tutorial/workflow) 与 [高阶篇](/docs/quick-start/v4/tutorial/advanced)

完成本篇后，你已经拥有了稳定的基础开发环境。接着让我们通过真实业务组件把 Tailwind CSS 4 的能力串联起来。

---

## 进阶篇：用 Tailwind CSS 4 构建真实页面


基础环境搭建完成后，真正的挑战来自“如何把抽象的原子类应用到真实业务”。本篇精选小程序常见的页面模块，结合 `tailwindcss@4` 的新指令，总结出一套从设计拆解到代码落地的流程。

## 工具优先的心智模型

Tailwind CSS 的核心不在于背公式，而是把 UI 拆成「布局」「排版」「状态」三个维度，然后使用类名组合快速拼装。Tailwind 4 进一步引入 `@theme`、`@utility` 等指令，让自定义能力与项目约束保持同步：

- `@theme` 管理设计令牌：颜色、间距、字号、阴影等
- `@utility` 声明可复用的工具类，代替传统的 `.btn { ... }`
- `@variant` / `@custom-variant` 管理状态类（如 `active:`、`dark:`）

掌握这些指令后，就可以在不离开 CSS 语法的前提下扩展 Tailwind。

## 1. 拆解一个卡片组件

以「订单卡片」为例，先在 `src/components/order-card/index.vue` 写出骨架：

```html title="src/components/order-card/index.vue"
<template>
  <view class="order-card">
    <view class="order-card__header">
      <text class="order-card__title">{{ title }}</text>
      <text class="order-card__status" :class="statusClass">{{ statusText }}</text>
    </view>
    <view class="order-card__meta">
      <text>{{ createdAt }}</text>
      <text>{{ amount }}</text>
    </view>
    <slot />
  </view>
</template>
```

接下来在 `src/components/order-card/index.css` 中使用 Tailwind 原子类重构：

```css title="src/components/order-card/index.css"
@reference "../../app.css";

/* 使用 @utility 提升可读性 */
@utility order-card {
  @apply block rounded-3xl bg-white shadow-lg shadow-slate-200/70 p-5 space-y-4;
}

@utility order-card__header {
  @apply flex items-center justify-between gap-3;
}

@utility order-card__title {
  @apply text-base font-semibold text-slate-900;
}

@utility order-card__meta {
  @apply flex items-center justify-between text-sm text-slate-500;
}

@utility order-card__status {
  @apply inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium uppercase tracking-[0.28em];
}

/* 通过 @variant 声明业务状态 */
@custom-variant status-pending (&[data-status="pending"]);
@custom-variant status-finished (&[data-status="finished"]);
@custom-variant status-failed (&[data-status="failed"]);

.order-card__status {
  @apply status-pending:bg-amber-100 status-pending:text-amber-600;
  @apply status-finished:bg-emerald-100 status-finished:text-emerald-600;
  @apply status-failed:bg-rose-100 status-failed:text-rose-600;
}
```

关键点：

- 使用 `@reference` 让局部样式文件继承入口 CSS 中的主题与工具
- `@utility` 让类名语义化，同时还能继续 `@apply` 原子类
- `@custom-variant`（Tailwind 4 新增）能让业务状态转换成语义化前缀

最后在组件实例上应用：

```html title="src/pages/index/index.vue"
<template>
  <order-card
    class="order-card"
    data-status="pending"
    title="小程序尊享套餐"
    status-text="待支付"
    created-at="2024-06-03"
    amount="¥199"
  >
    <view class="flex items-center gap-2 rounded-2xl bg-slate-50 px-4 py-3">
      <text class="text-xs font-medium text-slate-500">自动续费:</text>
      <switch class="scale-90" :checked="false" />
    </view>
  </order-card>
</template>
```

## 2. 构建可复用的设计令牌

Tailwind 4 把主题抽象为原生 CSS 变量。你可以在 `app.css` 中集中维护令牌，再通过 `@theme` 输出：

```css title="src/app.css" {2-7}
@import "weapp-tailwindcss/index.css";

@theme {
  --color-brand: oklch(66% 0.21 268);
  --color-brand-muted: oklch(80% 0.04 268);
  --radius-xl: 24px;
  --shadow-elevated: 0 18px 40px -20px rgb(99 102 241 / 45%);
}
```

然后在业务样式中直接引用这些变量，或结合 Tailwind 的 `bg-[...]` 写法：

```css
.order-card {
  @apply shadow-[var(--shadow-elevated)];
}

.order-card__status {
  @apply status-finished:bg-[var(--color-brand-muted)] status-finished:text-[var(--color-brand)];
}
```

得益于 CSS 变量特性，你还可以在不同页面覆写 `:root` 或对应容器的变量，以实现主题切换。

## 3. 管理复杂布局与响应式

小程序虽然没有传统意义上的宽度断点，但我们仍可以借助媒体查询、`min()` / `max()` 等函数实现容错布局：

```css
@layer utilities {
  @responsive {
    @media (min-width: 560px) {
      .md\\:card-grid {
        display: grid;
        grid-template-columns: repeat(2, minmax(0, 1fr));
        gap: clamp(16px, 4vw, 36px);
      }
    }
  }
}
```

在页面中配合默认的原子类即可：

```html
<view class="space-y-4 md:card-grid">
  <slot />
</view>
```

对于需要横向滚动的卡片，Tailwind 4 提供的 `snap-x`, `snap-mandatory`, `snap-center` 等类仍旧适用，不同端的处理逻辑交给 `weapp-tailwindcss`。

## 4. 多文件协作与团队约定

当项目迎来多人协作时，建议遵循以下约定：

1. **入口 CSS 只做聚合**：集中维护 `@import`、`@source` 与 `@theme`，其余逻辑拆到独立文件。
2. **组件目录内固定 `index.css`**：组件内声明 `@utility`、`@apply`，并写在组件同名文件夹下，便于按需引用。
3. **公共工具抽成包**：例如 `src/styles/utilities/forms.css`，内部声明所有表单相关的 `@utility`。
4. **lint 与提示配置**：确保团队成员的 VS Code `tailwindCSS.experimental.classRegex` 包含 `.wxml`、`.vue` 等模板。

## 5. 调试与性能提示

- Tailwind 4 的编译沿用增量模式，`pnpm run:watch` 时生成的原子类会写入缓存。需要彻底清理时删除 `.tailwind`、`node_modules/.cache/tailwind`。
- 小程序开发者工具不支持 `@layer`，若遇到覆盖问题，可以开启 `cssPresetEnv` 的降级行为，详情见 [高阶篇](/docs/quick-start/v4/tutorial/advanced)。
- 借助 `pnpm dev:h5`（部分框架提供）可快速在浏览器预览，调试完后再回到真机验证。

完成本篇后，你应该可以把 Tailwind 应用到实际业务模块，并形成一套可复用的组件写法。接下来，我们会关注性能优化、跨端适配与团队协作等更高阶的话题。

---

## HBuilderX


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

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

<UniAppHbuilderShared />

---

## uni-app cli vue3 vite(V4)


## 1. 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss weapp-tailwindcss
```

<Patch />

## 2. 配置 `vite.config.ts`

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      cssEntries: [
        // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
        path.resolve(import.meta.dirname, './src/app.css'),
      ],
    }),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss(),
      ],
    },
  },
});

```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
> `cssEntries` 必须指向纯 `css` 文件。不要把 `tailwindcss@4` 注册到 `scss`、`less` 等预处理样式文件中，否则样式和转译都可能失效。

## 3. 添加样式

<UniappCliStyle/>

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

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

{/* :::warning
这里必须创建一个额外的 `css` 文件，而不是直接在 `App.vue` 里的 `style` 标签下直接写，

这是因为 `@tailwindcss/vite` 目前只转化 `.css` 文件。后续可能会支持更多格式的文件，比如 `vue` 编译的中间文件

详见 http://github.com/tailwindlabs/tailwindcss/blob/main/packages/%40tailwindcss-vite/src/index.ts#L122 中的 `isCssFile` 判断
::: */}

## 参考模板

[uni-app-tailwindcss-v4](https://github.com/icebreaker-template/uni-app-tailwindcss-v4)

---

## uni-app cli vue2 webpack(V4)


:::caution
这条 `uni-app cli vue2 webpack` 路线已经不推荐，仓库中的对应 classic demo 也已经移除。

请优先使用 [uni-app cli vue3 vite](/docs/quick-start/v4/uni-app-vite)。
:::

## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

### 创建 `vue.config.js`

```js title="vue.config.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
/**
 * @type {import('@vue/cli-service').ProjectOptions}
 */
const config = {
  // some option...
  configureWebpack: (config) => {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
        cssEntries: [
          // 你 @import "weapp-tailwindcss/index.css"; 那个文件绝对路径
          path.resolve(__dirname, './src/app.css'),
        ],
      })
    )
  }
  // other option...
}

module.exports = config
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 配置 `postcss.config.js`

```js title="postcss.config.js"
const path = require('path')
const webpack = require('webpack')
const config = {
  parser: require('postcss-comment'),
  plugins: [
    // highlight-next-line
    require('@tailwindcss/postcss')(), // 只添加这一行
    require('postcss-import')({
      resolve (id, basedir, importOptions) {
        if (id.startsWith('~@/')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(3))
        } else if (id.startsWith('@/')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(2))
        } else if (id.startsWith('/') && !id.startsWith('//')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(1))
        }
        return id
      }
    }),

    require('autoprefixer')({
      remove: process.env.UNI_PLATFORM !== 'h5'
    }),
    require('@dcloudio/vue-cli-plugin-uni/packages/postcss')
  ]
}
if (webpack.version[0] > 4) {
  delete config.parser
}
module.exports = config
```

## 添加样式

<UniappCliStyle />

然后直接运行到小程序，微信开发者工具导入这个项目，即可看到效果

## 说明

本文仅为存量项目迁移和排查保留，不再提供推荐模板。

---

## uni-app x


:::warning
tailwindcss@4 版本，暂时只支持 hbuilderx uni-app x 跨 `h5` 和 `小程序` 平台，

原生安卓和IOS平台无法支持，因为 uni-app x 目前对 css 各种现代语法的兼容较差，兼容不了 tailwindcss@4 生成的样式

未来此功能的适配，取决于 uni-app x 团队对现代 css 的兼容程度

(2025-07-27)
:::

:::warning 布局限制
即使在当前可用的平台范围内，也不要把 `gap`、`gap-x-*`、`gap-y-*` 当作 `uni-app x` 可依赖能力。

`space-x-*`、`space-y-*` 也不要在 `uni-app x` 中使用。
:::

<UniAppHbuilderShared isX />

---

## Weapp-vite


<ExternalClassesReminder framework="weapp-vite" />

## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch/>

## 配置

更改 `vite.config.ts` 注册 `weapp-tailwindcss`

```js title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      cssEntries: [
        // app.css 的路径
        path.resolve(import.meta.dirname, './app.css'),
      ],
    }),
  ],
})
```

添加 `postcss.config.js` 注册 `@tailwindcss/postcss`

```js title="postcss.config.js"
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

## 添加样式

在项目目录下，小程序全局的 `app.css` 中，添加以下内容：

```css title="app.css"
@import "weapp-tailwindcss/index.css";
```

<CssImportReminder />

更改好配置之后，直接启动即可

---

## wxs的转义与处理


:::info
`2.5.2+` 版本中，已经添加了对 `wxs`,`sjs`等视图层运行 `js` 的转义和处理，默认关闭

具体见配置项:

- [`wxsMatcher`](/docs/api/options/matchers#wxsmatcher)
- [`inlineWxs`](/docs/api/options/matchers#inlinewxs)

:::

---

## weapp-tw CLI 使用指南

`weapp-tailwindcss` 自带一个 `weapp-tw` 命令行工具，负责提前给 Tailwind CSS 打补丁、生成类名缓存以及收集 token。以下内容介绍常用命令及最佳实践。

## 常见场景

| 场景 | 命令 | 说明 |
| --- | --- | --- |
| 给 Tailwind CSS 打补丁、注入 `rpx` 支持 | `npx weapp-tw patch` | 运行一次即可，推荐写在 `postinstall`；支持 `--cwd` 指向子包目录。 |
| 强制刷新补丁缓存后再打补丁 | `npx weapp-tw patch --clear-cache` | 默认不会清理缓存；仅在怀疑缓存导致补丁未生效或版本不一致时使用。 |
| 在 monorepo 针对子包补丁 | `pnpm --filter <pkg> exec weapp-tw patch --cwd .` | `pnpm` 场景建议显式传 `--cwd .`，每个子包只写入自己的缓存，避免 hoist 后的 `node_modules` 不一致。 |
| 一键扫描 workspace 并补丁 | `weapp-tw patch --workspace --cwd <repo-root>` | 自动读取 `pnpm-lock.yaml`/`pnpm-workspace.yaml` 批量补丁，跳过未安装 Tailwind 的包，并输出每个子包状态。 |
| 查看补丁应用/缺失情况 | `npx weapp-tw status --json` | 复用 `tailwindcss-patch` 的状态检查，输出各补丁是否已应用，可配合 `--cwd` 指定子包。 |
| 收集 Tailwind 产出的类名缓存 | `npx weapp-tw extract --css src/app.css` | 适用于 Tailwind v3/v4，v4 需传入 `--css`，生成 `.tw-patch/tw-class-cache.*`，支持 `--output`/`--format`。 |
| 输出 Tailwind token 和定位信息 | `npx weapp-tw tokens --format grouped-json` | 调试 `content` 配置时非常有用，可与 `--no-write` 一起纯输出。 |

## `patch` 子命令

### 功能

- 扫描当前工作目录所依赖的 `tailwindcss`，给其打上 `rpx` 单位补丁。
- 暴露 Tailwind 运行时上下文，供 `webpack`/`vite`/`gulp` 插件复用。
- 检测到未安装 Tailwind 时会输出中文警告。

### 常用参数

| 参数 | 默认值 | 含义 |
| --- | --- | --- |
| `--cwd <dir>` | `WEAPP_TW_PATCH_CWD` \| `INIT_CWD` \| `npm_config_local_prefix` \| 当前工作目录 | 指定要补丁的子包目录，等价于先 `cd`。默认会按顺序读取上述环境变量，避免在 `pnpm`/CI 里被 wrapper 覆盖成根目录。 |
| `--record-target` | `true` | 默认记录本次打补丁对应的 `tailwindcss` 根路径到子包专属的 `node_modules/.cache/weapp-tailwindcss/<hash>/tailwindcss-target.json`，包含 `cwd`、Tailwind 路径、补丁版本与时间戳；如需关闭请传 `--record-target false`。 |
| `--clear-cache` | `false` | 按需清理 `tailwindcss-patch` 缓存目录后再执行补丁。默认不清理，避免不必要的 IO 和 CI 侧效应。 |
| `--workspace` | `false` | 批量扫描 workspace（`pnpm-lock.yaml`/`pnpm-workspace.yaml`/`workspaces`），逐个子包执行 patch 并输出“补丁/跳过/失败”状态。 |

默认会记录补丁目标，运行日志类似：

```bash
$ pnpm --filter demo/native-ts weapp-tw patch
weapp-tw patch 绑定 Tailwind CSS -> ./node_modules/tailwindcss (v3.4.18)
记录 weapp-tw patch 目标 -> ./node_modules/.cache/weapp-tailwindcss/<hash>/tailwindcss-target.json
Tailwind CSS 运行时补丁已完成。
```

随后每次启动构建工具，运行时会输出 `tailwindcss-patcher 绑定 Tailwind CSS -> ...`；若检测到与缓存记录不一致，会自动重打补丁并刷新记录，无需手动清理跨包告警。若不希望生成记录，可在命令后追加 `--record-target false`。补丁记录按子包（package.json 路径 hash）隔离，避免 `pnpm` hoist 或 `workspace:` 互相引用时互相覆盖。

## `extract` 子命令

```bash
npx weapp-tw extract --css src/app.css --format lines
```

- `--css`：Tailwind 入口 CSS。v4 必填；v3 可省略以沿用 Tailwind 默认入口。
- `--output`：指定输出文件，默认写入 `.tw-patch/tw-class-cache.json`。
- `--format`：`json`/`lines`，配合 `--no-write` 可仅打印到终端。
- `--cwd` 与 `patch` 一致，也支持放在子包里执行。

生成的缓存可以让构建器快速读取 `tailwindcss` 编译结果，减少重复启动的开销。

## `tokens` 子命令

```bash
npx weapp-tw tokens --format grouped-json --group-key absolute
```

- `--format`：`json`、`lines` 或 `grouped-json`。后一种会按文件分组，便于排查 `content` 匹配不到的问题。
- `--group-key`：`relative`(默认)/`absolute`，决定输出路径的基准。
- `--no-write`：终端预览，不落盘；默认写入 `.tw-patch/tw-token-report.json`。

输出的数据包含扫描到的文件、类名 token、出现位置（行列）、以及被跳过的文件列表。

## `status` 子命令

```bash
npx weapp-tw status --cwd demo/native-ts
npx weapp-tw status --json
```

- 复用 `tailwindcss-patch` 的状态检查，按补丁列出 `applied`/`not-applied`/`skipped`/`unsupported`。
- `--cwd`：指定要检查的子包目录，默认沿用 `patch` 的自动推断。
- `--json`：输出 JSON 报告，方便 CI 或脚本读取。

## 快速排查指引

1. **始终在子包目录执行 `weapp-tw patch`**：`pnpm --filter my-demo weapp-tw patch --cwd demo/my-demo`。
2. **如确实不需要追踪，可传 `--record-target false`**，避免生成额外 JSON。
3. **看到自动重补丁/记录迁移提示**：确认日志里的 Tailwind 路径与子包一致，`pnpm --filter ... exec weapp-tw patch --cwd .` 或 `weapp-tw patch --workspace --cwd <repo-root>` 可避免 `INIT_CWD` 导致的跨包记录污染。
4. **类名缺失**： 用 `weapp-tw extract` 或 `weapp-tw tokens --no-write` 辅助定位是哪段代码没有被 Tailwind `content` 收录。
5. **需要强制指定根目录时**：在 monorepo 根执行 `WEAPP_TW_PATCH_CWD=$PWD weapp-tw patch --workspace`，可覆盖外层脚本设置的 `INIT_CWD`，确保一次性为所有子包补丁并写入各自的缓存记录。

配合这些命令，可以更直观地观察 Tailwind 依赖解析与补丁状态，减少“rpx 被当成颜色” 等由于上下游不一致导致的问题。

---

## uni-app x 专题


  
  
  
  
    跨端原子化样式方案
    Tailwind CSS × uni-app x
  

  
    
    一键使用模板项目（推荐）
  
  
    
    或者按步骤手动集成
  

## 这篇文档适合谁

- 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
- 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案
- 希望以最少的改动尽快起步，并有清晰的后续扩展路线

## 你将收获什么

- 完整的从 0 到 1 集成流程（含运行与验证）
- 可复用的模板项目与配置清单
- 多端开发的实践建议与避坑说明

:::info 支持范围
当前跨端集成仅支持 `tailwindcss@3.x`。  
`tailwindcss@4.x` 生成的 CSS 依赖诸多现代特性，`uni-app x` 暂未全部覆盖，故不建议在该场景使用 v4。
:::

## 最快开始

- 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可
- 想了解每一步：前往「手动集成」教程 → <Link to="/docs/uni-app-x/install">快速集成</Link>

## 开发建议（从用户出发）

- 推荐编辑器协作：用 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

1) 原生端样式约束更严格，例如文本必须使用 `<text>`，许多 CSS 特性仍在补齐中  
2) 如果你的页面在 Android 端无告警、展示正确，迁移到小程序与 Web 的心智负担会小很多  
3) 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`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

### 运行方式

目前 `uni-app x` 尚无 CLI，需通过 HBuilderX 进行运行与构建。  
建议配合 Android 模拟器进行开发调试。

## 接下来

- 跟着步骤手动完成集成：<Link to="/docs/uni-app-x/install">快速集成</Link>  
- 直接基于模板起步：<Link to="https://github.com/icebreaker-template/uni-app-x-hbuilderx">uni-app x + Tailwind 模板（HBuilderX）</Link>

---

## 快速集成


## 最简单：直接用模板项目（推荐）

立即上手而不纠结配置细节，点击下面链接即可：

  
    
    使用模板一键开始
  

打开后按 README 步骤，用 HBuilderX 运行到 Android 模拟器或真机即可看到效果。

---

## 手动集成（由浅入深）

你也可以按下面步骤，从零开始完成配置。

### 前置条件

- 已安装最新 HBuilderX
- 安装 Node.js（建议 ≥ 18）
- 建议准备 Android 模拟器（或真机），便于快速验证

### 1) 创建项目

在 HBuilderX 中创建一个全新的 `uni-app x` 项目；随后在项目根目录初始化 `package.json`：

```bash npm2yarn
npm init -y
```

> 也可以手动创建 `package.json` 文件。

### 2) 安装并引入 Tailwind CSS 3

```bash npm2yarn
# 安装 tailwindcss@3 所需依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 Tailwind 配置文件
npx tailwindcss init
```

在应用入口 `App.uvue` 中全局引入：

```html title="App.uvue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

### 3) 安装 weapp-tailwindcss 并添加补丁脚本

```bash npm2yarn
npm i -D weapp-tailwindcss
```

在 `package.json` 中增加 `postinstall` 脚本：

```json title="package.json"
{
  "scripts": {
    // highlight-next-line
    "postinstall": "weapp-tw patch"
  }
}
```

> 了解原因可阅读：weapp-tailwindcss 使用说明

### 4) 在 uni-app x 中注册 weapp-tailwindcss

先创建一个简单的路径工具函数，方便在配置里引用绝对路径：

```js title="shared.js"
const path = require('node:path')
function r(...args) {
  return path.resolve(__dirname, ...args)
}
module.exports = { r }
```

创建 `vite.config.ts` 并注册插件（注意 `uniAppX` 预设来自 `weapp-tailwindcss/presets`）：

```js title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin(
      uniAppX({
        base: __dirname,
        // uni-app x 官方推荐使用 px 作为单位
        unitsToPx: true,
      }),
    ),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss({
          config: r('./tailwind.config.js'),
        }),
      ],
    },
  },
})
```

#### CSS 单位转换（推荐）

`uni-app x` 官方推荐使用 `px` 作为长度单位，开启 `unitsToPx` 后会将 `rem/em/vw/vh/vmin/vmax/rpx` 统一转换为 `px`：

```js title="vite.config.ts"
UnifiedViteWeappTailwindcssPlugin(
  uniAppX({
    base: __dirname,
    unitsToPx: true,
  }),
)
```

需要自定义转换规则时可以传入对象，例如调整精度或覆盖单位映射：

```js title="vite.config.ts"
UnifiedViteWeappTailwindcssPlugin(
  uniAppX({
    base: __dirname,
    unitsToPx: {
      unitPrecision: 2,
      unitMap: {
        rem: 16,
        rpx: 0.5,
      },
    },
  }),
)
```

> 如果希望最终输出为 `rpx`，请不要启用 `unitsToPx`，改用 `rem2rpx` / `px2rpx`。

### 5) 配置 Tailwind

使用绝对路径包含所有需要提取原子类的文件：

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}'),
  ],
  corePlugins: {
    // 由 uni-app x 提供基础样式，这里关闭 preflight 避免冲突
    preflight: false,
  },
}
```

如需从更多目录提取样式，按需扩展 `content` 的 glob。

### 6) 运行与验证

- 在 HBuilderX 中点击「运行」并选择目标平台（推荐 Android 模拟器/真机）  
- 新建/打开任意页面，写入示例类名验证：

```html
<view class="p-4">
  <text class="text-xl text-red-500 font-medium">Hello Tailwind on uni-app x</text>
</view>
```

### 7) 编辑器智能提示（可选）

VS Code 配合插件体验最佳。为 Tailwind 扩展增加语言映射，让其识别 `uvue/uts`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

同时安装官方语言服务插件（ID: dcloud-ide.hbuilderx-language-services）以获得完整语法支持。

---

## 重要说明与限制

- 仅推荐在 `tailwindcss@3.x` 下跨端使用（v4 在该场景下暂不兼容）
- 原生 App 端对文本与部分 CSS 特性有约束：文本使用 `<text>` 元素，且样式需直接作用其上
- `uvue` 原生 App 端不支持 `gap`、`gap-x-*`、`gap-y-*`，因此 grid gap / flex gap 都不能作为可用能力来依赖
- `space-x-*`、`space-y-*` 在 `uni-app x` 中也不支持，不要作为布局方案使用
- 更稳妥的替代方案是直接对子项写 `mt-*` / `ml-*`，或在业务层封装固定结构的间距组件
- 如遇到 HBuilderX 控制台 CSS 警告，请按提示做兼容性调整或采用条件编译

---

## weapp-tailwindcss


## 配置项

- [UserDefinedOptions 总览](interfaces/UserDefinedOptions.md)
- [✅ 重要配置](options/important.md)
- [🧩 文件匹配](options/matchers.md)
- [🧭 生命周期](options/lifecycle.md)
- [⚙️ 一般配置](options/general.md)

## 接口

- [🗂️ 其他接口](other-interfaces.md)

---

## ApplyOptions


Preferred options for runtime patch behavior.

## 属性

### overwrite?

> `optional` **overwrite**: `boolean`

Whether patched files can be overwritten on disk.

***

### exposeContext?

> `optional` **exposeContext**: `boolean | ExposeContextOptions`

Whether to expose runtime Tailwind contexts (or configure how they are exposed).

***

### extendLengthUnits?

> `optional` **extendLengthUnits**: `false | ExtendLengthUnitsOptions`

Extends the length-unit patch or disables it entirely.

---

## CacheOptions


Configures how the Tailwind class cache is stored and where it lives on disk.

## 属性

### enabled?

> `optional` **enabled**: `boolean`

Whether caching is enabled.

***

### cwd?

> `optional` **cwd**: `string`

Working directory used when resolving cache paths.

***

### dir?

> `optional` **dir**: `string`

Directory where cache files are written.

***

### file?

> `optional` **file**: `string`

Cache filename. Defaults to `class-cache.json` inside the derived cache folder
when omitted.

***

### strategy?

> `optional` **strategy**: `CacheStrategy`

Strategy used when merging new class lists with an existing cache.

***

### driver?

> `optional` **driver**: `CacheDriver`

Backend used to persist the cache (`file`, `memory`, or `noop`). Defaults to `file`.

---

## DisabledOptions


禁用插件功能的细粒度选项。

## 添加于

^4.2.0

## 备注

适用于需要仅关闭部分行为（例如主插件流程），但保留其他预处理能力（如 Tailwind v4 的 `@import "tailwindcss"` 到 `@import "weapp-tailwindcss/index.css"` 的重写）。

## 属性

### plugin?

> `optional` **plugin**: `boolean`

禁用主插件流程，等同于 `disabled: true`。

#### 默认值

```ts
false
```

***

### rewriteCssImports?

> `optional` **rewriteCssImports**: `boolean`

禁用对 `@import "tailwindcss"` 到 `@import "weapp-tailwindcss/index.css"` 的预处理重写。

#### 默认值

```ts
false
```

---

## ExtractOptions


Preferred options for extraction output behavior.

## 属性

### write?

> `optional` **write**: `boolean`

Whether to produce an output file.

***

### file?

> `optional` **file**: `string`

Optional absolute or relative path to the output file.

***

### format?

> `optional` **format**: `"json" | "lines"`

Output format, defaults to JSON when omitted.

***

### pretty?

> `optional` **pretty**: `number | boolean`

Pretty-print spacing (truthy value enables indentation).

***

### removeUniversalSelector?

> `optional` **removeUniversalSelector**: `boolean`

Whether to strip the universal selector (`*`) from the final list.

---

## TailwindCssOptions


High-level Tailwind patch configuration shared across versions.

## 属性

### config?

> `optional` **config**: `string`

Path to a Tailwind config file when auto-detection is insufficient.

***

### cwd?

> `optional` **cwd**: `string`

Custom working directory used when resolving config-relative paths.

***

### postcssPlugin?

> `optional` **postcssPlugin**: `string`

Optional PostCSS plugin name to use instead of the default.

***

### version?

> `optional` **version**: `2 | 3 | 4`

Explicit Tailwind CSS major version used by the current project. When omitted, the installed package version is inferred.

***

### packageName?

> `optional` **packageName**: `string`

Tailwind package name if the project uses a fork.

***

### resolve?

> `optional` **resolve**: `PackageResolvingOptions`

Package resolution options forwarded to `local-pkg`.

***

### v2?

> `optional` **v2**: `TailwindV2Options`

Overrides applied when patching Tailwind CSS v2.

***

### v3?

> `optional` **v3**: `TailwindV3Options`

Overrides applied when patching Tailwind CSS v3.

***

### v4?

> `optional` **v4**: `TailwindV4Options`

Options specific to Tailwind CSS v4 patching.

---

## TailwindCssPatchOptions


Root configuration consumed by the Tailwind CSS patch runner.

## 属性

### projectRoot?

> `optional` **projectRoot**: `string`

Base directory used when resolving Tailwind resources.
Defaults to `process.cwd()`.

***

### tailwindcss?

> `optional` **tailwindcss**: `TailwindCssOptions`

Preferred Tailwind runtime configuration.

***

### apply?

> `optional` **apply**: `ApplyOptions`

Preferred patch toggles.

***

### extract?

> `optional` **extract**: `ExtractOptions`

Preferred extraction output settings.

***

### filter()?

> `optional` **filter()**: `((className: string) => boolean)`

Optional function that filters final class names.

#### 参数

##### className

`string`

#### 返回

`boolean`

***

### cache?

> `optional` **cache**: `boolean | CacheOptions`

Cache configuration or boolean to enable/disable quickly.

---

## TailwindV2Options


Configuration specific to Tailwind CSS v2 patching flows.

## 属性

### config?

> `optional` **config**: `string`

Path to a Tailwind config file when auto-detection is insufficient.

***

### cwd?

> `optional` **cwd**: `string`

Custom working directory used when resolving config-relative paths.

***

### postcssPlugin?

> `optional` **postcssPlugin**: `string`

Optional PostCSS plugin name to use instead of the default.

---

## TailwindV3Options


Configuration specific to Tailwind CSS v3 patching flows.

## 属性

### config?

> `optional` **config**: `string`

Path to a Tailwind config file when auto-detection is insufficient.

***

### cwd?

> `optional` **cwd**: `string`

Custom working directory used when resolving config-relative paths.

***

### postcssPlugin?

> `optional` **postcssPlugin**: `string`

Optional PostCSS plugin name to use instead of the default.

---

## TailwindV4Options


Additional configuration specific to Tailwind CSS v4 extraction.

## 属性

### base?

> `optional` **base**: `string`

Base directory used when resolving v4 content sources and configs.

***

### css?

> `optional` **css**: `string`

Raw CSS passed directly to the v4 design system.

***

### cssEntries?

> `optional` **cssEntries**: `string[]`

Set of CSS entry files that should be scanned for `@config` directives.

***

### sources?

> `optional` **sources**: `SourceEntry[]`

Overrides the content sources scanned by the oxide scanner.

---

## UserDefinedOptions

## 分组入口

- [✅ 重要配置](../options/important.md) (17)
- [🧩 文件匹配](../options/matchers.md) (6)
- [🧭 生命周期](../options/lifecycle.md) (4)
- [⚙️ 一般配置](../options/general.md) (17)

---

## ⚙️ 一般配置

本页收录 17 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [supportCustomLengthUnitsPatch](#supportcustomlengthunitspatch) | <code>boolean &#124; ILengthUnitsPatchOptions</code> | — | 控制 Tailwind 自定义长度单位补丁。 |
| [appType](#apptype) | <code>AppType</code> | — | 声明所使用的框架类型。 |
| [arbitraryValues](#arbitraryvalues) | <code>IArbitraryValues</code> | — | TailwindCSS 任意值的相关配置。 |
| [jsPreserveClass](#jspreserveclass) | <code>(keyword: string) => boolean &#124; undefined</code> | <code>保留所有带 `*` js字符串字面量</code> | 控制 JS 字面量是否需要保留。 |
| [staleClassNameFallback](#staleclassnamefallback) | <code>boolean</code> | — | 兼容字段：不再参与 JS 候选判定。 |
| [jsArbitraryValueFallback](#jsarbitraryvaluefallback) | <code>boolean &#124; "auto"</code> | — | 控制 JS 任意值类名在 classNameSet 异常时的受控兜底策略。 |
| [replaceRuntimePackages](#replaceruntimepackages) | <code>boolean &#124; Record<string, string></code> | — | 是否替换运行时依赖包名。 |
| [disabledDefaultTemplateHandler](#disableddefaulttemplatehandler) | <code>boolean</code> | <code>false</code> | 禁用默认的 `wxml` 模板替换器。 |
| [tailwindcssBasedir](#tailwindcssbasedir) | <code>string</code> | — | 指定用于获取 Tailwind 上下文的路径。 |
| [cache](#cache) | <code>boolean &#124; ICreateCacheReturnType</code> | — | 控制缓存策略。 |
| [babelParserOptions](#babelparseroptions) | <code>(Partial<Options> & { cache?: boolean; cacheKey?: string; })</code> | — | `@babel/parser` 的配置选项。 |
| [cssChildCombinatorReplaceValue](#csschildcombinatorreplacevalue) | <code>string &#124; string[]</code> | <code>'view + view'</code> | 自定义 Tailwind 子组合器的替换值。 |
| [postcssOptions](#postcssoptions) | <code>Partial<Omit<import("/Users/yangqiming/Documents/GitHub/weapp-tailwindcss/node_modules/.pnpm/postcss-load-config@6.0.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_yaml@2.8.3/node_modules/postcss-load-config/src/index").Result, "file">></code> | — | `postcss` 的配置选项。 |
| [cssRemoveHoverPseudoClass](#cssremovehoverpseudoclass) | <code>boolean</code> | <code>`true`</code> | 是否移除 CSS 中的 `:hover` 选择器。 |
| [cssRemoveProperty](#cssremoveproperty) | <code>boolean</code> | <code>`true`</code> | 是否移除 `@property` 节点。 |
| [tailwindcssPatcherOptions](#tailwindcsspatcheroptions) | <code>TailwindCssPatchOptions</code> | — | 自定义 patcher 参数。 |
| [logLevel](#loglevel) | <code>"info" &#124; "warn" &#124; "error" &#124; "silent"</code> | — | 控制命令行日志输出级别。 |

## 详细说明

### supportCustomLengthUnitsPatch

> 可选 | 类型: `boolean | ILengthUnitsPatchOptions`

控制 Tailwind 自定义长度单位补丁。

#### 参阅

://github.com/sonofmagic/weapp-tailwindcss/issues/110

#### 备注

TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 `rpx` 识别为颜色。本选项默认开启以注入 `rpx` 支持。当 Node.js 在插件执行前已缓存 `tailwindcss` 模块时，首轮运行可能未生效，可通过在 `postinstall` 中执行 `weapp-tw patch` 提前打补丁。
```diff
"scripts": {
+  "postinstall": "weapp-tw patch"
}
```

### appType

> 可选 | 类型: `AppType`

声明所使用的框架类型。

#### 备注

用于辅助定位主要的 CSS bundle，以便默认的 `mainCssChunkMatcher` 做出更准确的匹配，未传入时将尝试自动猜测变量注入位置。

### arbitraryValues

> 可选 | 类型: `IArbitraryValues`

TailwindCSS 任意值的相关配置。

### jsPreserveClass

> 可选 | 类型: `(keyword: string) => boolean | undefined` | 默认值: `保留所有带 \`*\` js字符串字面量` | 版本: ^2.6.1

控制 JS 字面量是否需要保留。

#### 备注

当 Tailwind 与 JS 字面量冲突时，可通过回调返回 `true` 保留当前值，返回 `false` 或 `undefined` 则继续转义。默认保留所有带 `*` 的字符串字面量。

#### 默认值

```ts
保留所有带 `*` js字符串字面量
```

#### 参数

##### keyword

`string`

#### 返回

`boolean | undefined`

### staleClassNameFallback

> 可选 | 类型: `boolean`

兼容字段：不再参与 JS 候选判定。

#### 备注

JS 转译统一采用 `classNameSet` 精确匹配策略，仅转换 tailwindcss-patch 提供的类名集合。

### jsArbitraryValueFallback

> 可选 | 类型: `boolean | "auto"`

控制 JS 任意值类名在 classNameSet 异常时的受控兜底策略。

#### 备注

为避免误伤业务字符串，兜底仅在 class 语义上下文生效。
- `false`：关闭兜底；
- `true`：始终开启受控兜底；
- `'auto'`：仅 TailwindCSS v4 且 classNameSet 为空时启用。

### replaceRuntimePackages

> 可选 | 类型: `boolean | Record<string, string>`

是否替换运行时依赖包名。

#### 备注

适用于运行时包名需要重定向的场景，例如：
- 小程序侧无法直接安装 `tailwind-merge`/`class-variance-authority`/`tailwind-variants`，需要替换为内置的 weapp 版本。
- 企业内私有镜像/多包发布导致运行时包名不同，希望在转换后统一到目标包名。
传入 `true` 使用内置替换表，或传入对象自定义映射。

#### 示例

```ts
replaceRuntimePackages: {
  'tailwind-merge': '@weapp-tailwindcss/merge',
  'class-variance-authority': '@weapp-tailwindcss/cva',
}
```

### disabledDefaultTemplateHandler

> 可选 | 类型: `boolean` | 默认值: `false` | 版本: ^2.6.2

禁用默认的 `wxml` 模板替换器。

#### 备注

启用后模板匹配完全交由 [`customAttributes`](/docs/api/options/important#customattributes) 管理，需要自行覆盖默认的 `class` / `hover-class` 等匹配规则。

#### 默认值

```ts
false
```

### tailwindcssBasedir

> 可选 | 类型: `string` | 版本: ^2.9.3

指定用于获取 Tailwind 上下文的路径。

#### 备注

在 linked 或 monorepo 场景下可手动指向目标项目的 `package.json` 所在目录。

### cache

> 可选 | 类型: `boolean | ICreateCacheReturnType` | 版本: ^3.0.11

控制缓存策略。

### babelParserOptions

> 可选 | 类型: `(Partial<Options> & { cache?: boolean; cacheKey?: string; })` | 版本: ^3.2.0

`@babel/parser` 的配置选项。

### cssChildCombinatorReplaceValue

> 可选 | 类型: `string | string[]` | 默认值: `'view + view'`

自定义 Tailwind 子组合器的替换值。

#### 备注

为兼容小程序缺乏 `:not([hidden])~` 支持的限制，默认会将 `.space-x-4` 等选择器替换为 `view + view`。可传入字符串或字符串数组以扩展适用标签。
```css
// 数组示例
.space-y-4>view + view,text + text{}

// 字符串示例
.space-y-4>view,text,button,input ~ view,text,button,input{}
```

#### 默认值

```ts
'view + view'
```

### postcssOptions

> 可选 | 类型: `Partial<Omit<import("/Users/yangqiming/Documents/GitHub/weapp-tailwindcss/node_modules/.pnpm/postcss-load-config@6.0.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_yaml@2.8.3/node_modules/postcss-load-config/src/index").Result, "file">>` | 版本: ^3.2.0

`postcss` 的配置选项。

### cssRemoveHoverPseudoClass

> 可选 | 类型: `boolean` | 默认值: `\`true\`` | 版本: ^3.2.1

是否移除 CSS 中的 `:hover` 选择器。

#### 参阅

://github.com/sonofmagic/weapp-tailwindcss/issues/293

#### 备注

小程序不支持 `:hover`，需要使用组件的 `hover-class`，因此默认删除相关节点。

#### 默认值

`true`

### cssRemoveProperty

> 可选 | 类型: `boolean` | 默认值: `\`true\`` | 版本: ^4.1.2

是否移除 `@property` 节点。

#### 备注

微信小程序可识别 `@property`，但支付宝暂不支持，默认移除以避免构建失败。

#### 默认值

`true`

### tailwindcssPatcherOptions

> 可选 | 类型: `TailwindCssPatchOptions`

自定义 patcher 参数。

### logLevel

> 可选 | 类型: `"info" | "warn" | "error" | "silent"`

控制命令行日志输出级别。

#### 备注

默认 `info`，可设置为 `silent` 屏蔽全部输出。

---

## ✅ 重要配置

本页收录 17 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [disabled](#disabled) | <code>boolean &#124; DisabledOptions</code> | — | 是否禁用此插件。 |
| [customAttributes](#customattributes) | <code>ICustomAttributes</code> | — | 自定义 `wxml` 标签属性的转换规则。 |
| [customReplaceDictionary](#customreplacedictionary) | <code>Record<string, string></code> | <code>MappingChars2String</code> | 自定义 class 名称的替换字典。 |
| [ignoreTaggedTemplateExpressionIdentifiers](#ignoretaggedtemplateexpressionidentifiers) | <code>(string &#124; RegExp)[]</code> | <code>['weappTwIgnore']</code> | 忽略指定标签模板表达式中的标识符。 |
| [ignoreCallExpressionIdentifiers](#ignorecallexpressionidentifiers) | <code>(string &#124; RegExp)[]</code> | — | 忽略指定调用表达式中的标识符。 |
| [cssPreflight](#csspreflight) | <code>CssPreflightOptions</code> | — | 控制在视图节点上注入的 CSS 预设。 |
| [cssPreflightRange](#csspreflightrange) | <code>"all"</code> | — | 控制 `cssPreflight` 注入的 DOM 选择器范围。 |
| [cssCalc](#csscalc) | <code>boolean &#124; (string &#124; RegExp)[] &#124; CssCalcOptions</code> | — | 预计算 CSS 变量或 `calc` 表达式的结果。 |
| [injectAdditionalCssVarScope](#injectadditionalcssvarscope) | <code>boolean</code> | <code>false</code> | 是否额外注入 `tailwindcss css var scope`。 |
| [rewriteCssImports](#rewritecssimports) | <code>boolean</code> | <code>true</code> | 是否在 webpack/vite 阶段自动把 CSS 中的 `@import 'tailwindcss'` 映射为 `weapp-tailwindcss`。 |
| [cssSelectorReplacement](#cssselectorreplacement) | <code>{ root?: string &#124; string[] &#124; false; universal?: string &#124; string[] &#124; false; }</code> | 详见下方 | 控制 CSS 选择器的替换规则。 |
| [rem2rpx](#rem2rpx) | <code>boolean &#124; Rem2rpxOptions</code> | — | rem 到 rpx 的转换配置。 |
| [px2rpx](#px2rpx) | <code>boolean &#124; Px2rpxOptions</code> | — | px 到 rpx 的转换配置。 |
| [unitsToPx](#unitstopx) | <code>boolean &#124; UnitsToPxOptions</code> | — | 多单位转 px 的转换配置。 |
| [cssPresetEnv](#csspresetenv) | <code>PresetEnvOptions</code> | — | `postcss-preset-env` 的配置项。 |
| [tailwindcss](#tailwindcss) | <code>import("/Users/yangqiming/Documents/GitHub/weapp-tailwindcss/packages/weapp-tailwindcss/src/typedoc.export").TailwindCssOptions</code> | — | 为不同版本的 Tailwind 配置行为。 |
| [cssEntries](#cssentries) | <code>string[]</code> | — | 指定 tailwindcss@4 的入口 CSS。 |

## 详细说明

### disabled

> 可选 | 类型: `boolean | DisabledOptions`

是否禁用此插件。

#### 备注

在多平台构建场景下常用：小程序构建保持默认，非小程序环境（H5、App）传入 `true` 即可跳过转换。

#### 示例

```ts
// uni-app vue3 vite

const isH5 = process.env.UNI_PLATFORM === 'h5'
const isApp = process.env.UNI_PLATFORM === 'app'
const disabled = isH5 || isApp

uvtw({
  disabled,
})
```

### customAttributes

> 可选 | 类型: `ICustomAttributes`

自定义 `wxml` 标签属性的转换规则。

#### 备注

默认会转换所有标签上的 `class` 与 `hover-class`。此配置允许通过 `Map` 或对象为特定标签指定需要转换的属性字符串或正则表达式数组。
- 使用 `'*'` 作为键可为所有标签追加通用规则。
- 支持传入 `Map<string | RegExp, (string | RegExp)[]>` 以满足复杂匹配需求。
- 常见场景包括通过组件 `prop` 传递类名，或对三方组件的自定义属性做匹配，更多讨论见 [issue#129](https://github.com/sonofmagic/weapp-tailwindcss/issues/129#issuecomment-1340914688) 与 [issue#134](https://github.com/sonofmagic/weapp-tailwindcss/issues/134#issuecomment-1351288238)。
如果自定义规则已经覆盖默认的 `class`/`hover-class`，可开启 [`disabledDefaultTemplateHandler`](/docs/api/options/general#disableddefaulttemplatehandler) 以关闭内置模板处理器。

#### 示例

```js
const customAttributes = {
  '*': [/[A-Za-z]?[A-Za-z-]*[Cc]lass/],
  'van-image': ['custom-class'],
  'ice-button': ['testClass'],
}
```

### customReplaceDictionary

> 可选 | 类型: `Record<string, string>` | 默认值: `MappingChars2String`

自定义 class 名称的替换字典。

#### 备注

默认策略会将小程序不允许的字符映射为等长度的替代字符串，因此无法通过结果反推出原始类名。如需完全自定义，可传入 `Record<string, string>`，只需确保生成的类名不会与已有样式冲突。示例参考 [dic.ts](https://github.com/sonofmagic/weapp-core/blob/main/packages/escape/src/dic.ts)。

#### 默认值

```ts
MappingChars2String
```

### ignoreTaggedTemplateExpressionIdentifiers

> 可选 | 类型: `(string | RegExp)[]` | 默认值: `['weappTwIgnore']` | 版本: ^4.0.0

忽略指定标签模板表达式中的标识符。

#### 备注

当模板字符串被这些标识符包裹时，将跳过转义处理。

#### 默认值

```ts
['weappTwIgnore']
```

### ignoreCallExpressionIdentifiers

> 可选 | 类型: `(string | RegExp)[]` | 版本: ^4.0.0

忽略指定调用表达式中的标识符。

#### 备注

使用这些方法包裹的模板字符串或字符串字面量会跳过转义，常与 `@weapp-tailwindcss/merge` 配合（如 `['twMerge', 'twJoin', 'cva']`）。

### cssPreflight

> 可选 | 类型: `CssPreflightOptions`

控制在视图节点上注入的 CSS 预设。

#### 参阅

://github.com/sonofmagic/weapp-tailwindcss/issues/7

#### 备注

默认会向所有 `view`/`text` 元素注入 Tailwind 风格的基础样式，可通过此配置禁用、调整或补充规则，受 `cssPreflightRange` 影响。

#### 示例

```js
cssPreflight: {
  'box-sizing': 'border-box',
  'border-width': '0',
  'border-style': 'solid',
  'border-color': 'currentColor',
}

cssPreflight: false

cssPreflight: {
  'box-sizing': false,
  background: 'black',
}
```

### cssPreflightRange

> 可选 | 类型: `"all"`

控制 `cssPreflight` 注入的 DOM 选择器范围。

#### 参阅

://github.com/sonofmagic/weapp-tailwindcss/pull/62

#### 备注

仅 `view`、`text` 及其伪元素会受影响。设置为 `'all'` 可以覆盖所有元素，此时需自行处理与宿主默认样式的冲突。

### cssCalc

> 可选 | 类型: `boolean | (string | RegExp)[] | CssCalcOptions` | 版本: ^4.3.0

预计算 CSS 变量或 `calc` 表达式的结果。

#### 备注

解决部分机型对 `calc` 计算不一致的问题，可传入布尔值、选项对象或自定义匹配列表（支持正则）。在启用计算后，可通过 `includeCustomProperties` 指定需要保留的变量。

#### 示例

```css
// 原始输出
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

```css
// 启用 cssCalc 后
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
```

```js
cssCalc: ['--spacing']
cssCalc: { includeCustomProperties: ['--spacing'] }
```

### injectAdditionalCssVarScope

> 可选 | 类型: `boolean` | 默认值: `false` | 版本: ^2.6.0

是否额外注入 `tailwindcss css var scope`。

#### 备注

当构建链路（例如 `@tarojs/plugin-html`）移除了包含 `*` 的选择器时，可启用该选项重新写入变量作用域，以避免渐变等功能失效。

#### 默认值

```ts
false
```

### rewriteCssImports

> 可选 | 类型: `boolean` | 默认值: `true`

是否在 webpack/vite 阶段自动把 CSS 中的 `@import 'tailwindcss'` 映射为 `weapp-tailwindcss/index.css`。

#### 备注

开启后打包链路只会在处理样式时拦截 `tailwindcss` 的导入路径（JS/TS `import 'tailwindcss'` 不会被修改），让源码可以继续写 `@import 'tailwindcss';`，同时输出 `weapp-tailwindcss/index.css` 的样式。传入 `false` 可完全关闭该行为。

#### 默认值

```ts
true
```

### cssSelectorReplacement

> 可选 | 类型: `{ root?: string | string[] | false; universal?: string | string[] | false; }` | 默认值: 详见下方

控制 CSS 选择器的替换规则。

#### 默认值

`ts 'page'` |
| `universal?` | `string` \| `false` | **`Default`** `ts 'view'` |

### rem2rpx

> 可选 | 类型: `boolean | Rem2rpxOptions` | 版本: ^3.0.0

rem 到 rpx 的转换配置。

#### 备注

传入 `true` 使用默认配置，或提供 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) 支持的完整选项。
```ts
{
  rootValue: 32,
  propList: ['*'],
  transformUnit: 'rpx',
}
```

### px2rpx

> 可选 | 类型: `boolean | Px2rpxOptions` | 版本: ^4.3.0

px 到 rpx 的转换配置。

#### 备注

传入 `true` 启用默认映射（`1px = 1rpx`），或通过对象自定义更多行为。

### unitsToPx

> 可选 | 类型: `boolean | UnitsToPxOptions`

多单位转 px 的转换配置。

#### 备注

传入 `true` 启用默认映射（postcss-units-to-px 默认单位表），或通过对象自定义行为。
默认关闭。

### cssPresetEnv

> 可选 | 类型: `PresetEnvOptions` | 版本: ^4.0.0

`postcss-preset-env` 的配置项。

#### 参阅

- ://preset-env.cssdb.org/
- ://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme

### tailwindcss

> 可选 | 类型: `import("/Users/yangqiming/Documents/GitHub/weapp-tailwindcss/packages/weapp-tailwindcss/src/typedoc.export").TailwindCssOptions` | 版本: ^4.0.0

为不同版本的 Tailwind 配置行为。

### cssEntries

> 可选 | 类型: `string[]` | 版本: ^4.2.6

指定 tailwindcss@4 的入口 CSS。

#### 备注

未配置时无法加载自定义插件，等价于设置 `tailwindcss.v4.cssEntries`。

---

## 🧭 生命周期

本页收录 4 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [onLoad](#onload) | <code>(() => void)</code> | — | 插件 `apply` 初始调用时触发。 |
| [onStart](#onstart) | <code>(() => void)</code> | — | 开始处理前触发。 |
| [onUpdate](#onupdate) | <code>(filename: string, oldVal: string, newVal: string) => void</code> | — | 匹配并修改文件后触发。 |
| [onEnd](#onend) | <code>(() => void)</code> | — | 结束处理时触发。 |

## 详细说明

### onLoad

> 可选 | 类型: `(() => void)`

插件 `apply` 初始调用时触发。

#### 返回

`void`

### onStart

> 可选 | 类型: `(() => void)`

开始处理前触发。

#### 返回

`void`

### onUpdate

> 可选 | 类型: `(filename: string, oldVal: string, newVal: string) => void`

匹配并修改文件后触发。

#### 参数

##### filename

`string`

##### oldVal

`string`

##### newVal

`string`

#### 返回

`void`

### onEnd

> 可选 | 类型: `(() => void)`

结束处理时触发。

#### 返回

`void`

---

## 🧩 文件匹配

本页收录 6 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [htmlMatcher](#htmlmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的 `wxml` 等模板文件。 |
| [cssMatcher](#cssmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的 `wxss` 等样式文件。 |
| [jsMatcher](#jsmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的编译后 `js` 文件。 |
| [mainCssChunkMatcher](#maincsschunkmatcher) | <code>(name: string, appType?: AppType) => boolean</code> | — | 匹配负责注入 Tailwind CSS 变量作用域的 CSS Bundle。 |
| [wxsMatcher](#wxsmatcher) | <code>(name: string) => boolean</code> | <code>()=>false</code> | 匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。 |
| [inlineWxs](#inlinewxs) | <code>boolean</code> | <code>false</code> | 是否转义 `wxml` 中的内联 `wxs`。 |

## 详细说明

### htmlMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的 `wxml` 等模板文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### cssMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的 `wxss` 等样式文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### jsMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的编译后 `js` 文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### mainCssChunkMatcher

> 可选 | 类型: `(name: string, appType?: AppType) => boolean`

匹配负责注入 Tailwind CSS 变量作用域的 CSS Bundle。

#### 备注

在处理 `::before`/`::after` 等不兼容选择器时，建议手动指定文件位置。

#### 参数

##### name

`string`

##### appType?

`AppType`

#### 返回

`boolean`

### wxsMatcher

> 可选 | 类型: `(name: string) => boolean` | 默认值: `()=>false`

匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。

#### 备注

配置前请确保在 `tailwind.config.js` 的 `content` 中包含对应格式。

#### 默认值

```ts
()=>false
```

#### 参数

##### name

`string`

#### 返回

`boolean`

### inlineWxs

> 可选 | 类型: `boolean` | 默认值: `false`

是否转义 `wxml` 中的内联 `wxs`。

#### 备注

使用前同样需要在 `tailwind.config.js` 中声明 `wxs` 格式。

#### 默认值

```ts
false
```

#### 示例

```html
<!-- index.wxml -->
<wxs module="inline">
// 我是内联wxs
// 下方的类名会被转义
var className = "after:content-['我是className']"
module.exports = {
className: className
}
</wxs>
<wxs src="./index.wxs" module="outside"/>
<view><view class="{{inline.className}}"></view><view class="{{outside.className}}"></view></view>
```

---

## 🗂️ 其他接口

以下接口用于补充配置或运行时能力，本页面仅提供索引。

- [ApplyOptions](./interfaces/ApplyOptions.md) - Preferred options for runtime patch behavior.
- [CacheOptions](./interfaces/CacheOptions.md) - Configures how the Tailwind class cache is stored and where it lives on disk.
- [DisabledOptions](./interfaces/DisabledOptions.md) - 禁用插件功能的细粒度选项。
- [ExtractOptions](./interfaces/ExtractOptions.md) - Preferred options for extraction output behavior.
- [TailwindCssOptions](./interfaces/TailwindCssOptions.md) - High-level Tailwind patch configuration shared across versions.
- [TailwindCssPatchOptions](./interfaces/TailwindCssPatchOptions.md) - Root configuration consumed by the Tailwind CSS patch runner.
- [TailwindV2Options](./interfaces/TailwindV2Options.md) - Configuration specific to Tailwind CSS v2 patching flows.
- [TailwindV3Options](./interfaces/TailwindV3Options.md) - Configuration specific to Tailwind CSS v3 patching flows.
- [TailwindV4Options](./interfaces/TailwindV4Options.md) - Additional configuration specific to Tailwind CSS v4 extraction.

---

## Class: UnifiedWebpackPluginV5

**`Name`**

UnifiedWebpackPluginV5

**`Description`**

webpack5 核心转义插件

**`Link`**

https://tw.icebreaker.top/docs/intro

## Implements

- [`IBaseWebpackPlugin`](../interfaces/IBaseWebpackPlugin.md)

## Constructors

### constructor

• **new UnifiedWebpackPluginV5**(`options?`): [`UnifiedWebpackPluginV5`](UnifiedWebpackPluginV5.md)

#### Parameters

| Name      | Type                                                        |
| :-------- | :---------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](../interfaces/UserDefinedOptions.md) |

#### Returns

[`UnifiedWebpackPluginV5`](UnifiedWebpackPluginV5.md)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:24](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L24)

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[appType](../interfaces/IBaseWebpackPlugin.md#apptype)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:22](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L22)

---

### options

• **options**: `Required`<`Omit`<[`UserDefinedOptions`](../interfaces/UserDefinedOptions.md), `"customReplaceDictionary"` \| `"supportCustomLengthUnitsPatch"` \| [`GlobOrFunctionMatchers`](../#globorfunctionmatchers)\> & \{ `cssMatcher`: (`name`: `string`) => `boolean` ; `htmlMatcher`: (`name`: `string`) => `boolean` ; `jsMatcher`: (`name`: `string`) => `boolean` ; `mainCssChunkMatcher`: (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean` ; `wxsMatcher`: (`name`: `string`) => `boolean` } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](../#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](../#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: `false` \| [`ILengthUnitsPatchOptions`](../interfaces/ILengthUnitsPatchOptions.md) ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](../interfaces/ITemplateHandlerOptions.md)) => `string` }\>

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[options](../interfaces/IBaseWebpackPlugin.md#options)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:21](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L21)

## Methods

### apply

▸ **apply**(`compiler`): `void`

#### Parameters

| Name       | Type       |
| :--------- | :--------- |
| `compiler` | `Compiler` |

#### Returns

`void`

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[apply](../interfaces/IBaseWebpackPlugin.md#apply)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:32](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L32)

---

## weapp-tailwindcss-webpack-plugin

## Classes

- [UnifiedWebpackPluginV5](classes/UnifiedWebpackPluginV5.md)

## Interfaces

- [IArbitraryValues](interfaces/IArbitraryValues.md)
- [IBaseWebpackPlugin](interfaces/IBaseWebpackPlugin.md)
- [ICommonReplaceOptions](interfaces/ICommonReplaceOptions.md)
- [ILengthUnitsPatchDangerousOptions](interfaces/ILengthUnitsPatchDangerousOptions.md)
- [ILengthUnitsPatchOptions](interfaces/ILengthUnitsPatchOptions.md)
- [IPropValue](interfaces/IPropValue.md)
- [ITemplateHandlerOptions](interfaces/ITemplateHandlerOptions.md)
- [InternalCssSelectorReplacerOptions](interfaces/InternalCssSelectorReplacerOptions.md)
- [InternalPatchResult](interfaces/InternalPatchResult.md)
- [RawSource](interfaces/RawSource.md)
- [UserDefinedOptions](interfaces/UserDefinedOptions.md)

## Type Aliases

### AppType

Ƭ **AppType**: `"uni-app"` \| `"uni-app-vite"` \| `"taro"` \| `"remax"` \| `"rax"` \| `"native"` \| `"kbone"` \| `"mpx"`

#### Defined in

[types.ts:10](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L10)

---

### CreateJsHandlerOptions

Ƭ **CreateJsHandlerOptions**: `Omit`<[`IJsHandlerOptions`](#ijshandleroptions), `"classNameSet"`\>

#### Defined in

[types.ts:502](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L502)

---

### CssPreflightOptions

Ƭ **CssPreflightOptions**: \{ `[key: CssPresetProps]`: `string` \| `number` \| `boolean`; } \| `false`

#### Defined in

[types.ts:19](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L19)

---

### CssPresetProps

Ƭ **CssPresetProps**: `string`

#### Defined in

[types.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L17)

### GlobOrFunctionMatchers

Ƭ **GlobOrFunctionMatchers**: `"htmlMatcher"` \| `"cssMatcher"` \| `"jsMatcher"` \| `"mainCssChunkMatcher"` \| `"wxsMatcher"`

#### Defined in

[types.ts:460](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L460)

---

### ICustomAttributes

Ƭ **ICustomAttributes**: `Record`<`string`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>\> \| `Map`<`string` \| `RegExp`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>\>

#### Defined in

[types.ts:50](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L50)

---

### ICustomAttributesEntities

Ƭ **ICustomAttributesEntities**: [`string` \| `RegExp`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>][]

#### Defined in

[types.ts:52](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L52)

---

### IJsHandlerOptions

Ƭ **IJsHandlerOptions**: `Object`

#### Type declaration

| Name               | Type                                                                             |
| :----------------- | :------------------------------------------------------------------------------- |
| `arbitraryValues?` | [`IArbitraryValues`](interfaces/IArbitraryValues.md)                             |
| `classNameSet`     | `Set`<`string`\>                                                                 |
| `escapeMap?`       | `Record`<`string`, `string`\>                                                    |
| `generateMap?`     | `boolean`                                                                        |
| `jsPreserveClass?` | (`keyword`: `string`) => `boolean` \| `undefined`                                |
| `minifiedJs?`      | `boolean`                                                                        |
| `needEscaped?`     | `boolean`                                                                        |
| `strategy?`        | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md)[``"jsEscapeStrategy"``] |

#### Defined in

[types.ts:54](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L54)

---

### IStyleHandlerOptions

Ƭ **IStyleHandlerOptions**: [`RequiredStyleHandlerOptions`](#requiredstylehandleroptions) & \{ `ctx?`: `IContext` ; `postcssOptions?`: [`LoadedPostcssOptions`](#loadedpostcssoptions) ; `cssRemoveProperty?`: `boolean` ; `cssRemoveHoverPseudoClass?`: `boolean` ; `cssPresetEnv?`: [`PresetEnvOptions`](#presetenvoptions) ; `cssCalc?`: `boolean` \| [`CssCalcOptions`](#csscalcoptions) \| (`string` \| `RegExp`)[] ; `atRules?`: \{ `property?`: `boolean` ; `supports?`: `boolean` ; `media?`: `boolean`  } ; `uniAppX?`: `boolean` ; `majorVersion?`: `number`  }

#### Defined in

[types.ts:41](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L41)

---

### InternalPostcssOptions

Ƭ **InternalPostcssOptions**: `Pick`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), `"cssMatcher"` \| `"mainCssChunkMatcher"` \| `"cssPreflight"` \| `"replaceUniversalSelectorWith"` \| `"cssPreflightRange"` \| `"disabled"`\>

#### Defined in

[types.ts:479](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L479)

---

### InternalUserDefinedOptions

Ƭ **InternalUserDefinedOptions**: `Required`<`Omit`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), [`GlobOrFunctionMatchers`](#globorfunctionmatchers) \| `"supportCustomLengthUnitsPatch"` \| `"customReplaceDictionary"`\> & \{ [K in GlobOrFunctionMatchers]: K extends "mainCssChunkMatcher" ? Function : Function } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: [`ILengthUnitsPatchOptions`](interfaces/ILengthUnitsPatchOptions.md) \| `false` ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](interfaces/ITemplateHandlerOptions.md)) => `string` }\>

#### Defined in

[types.ts:462](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L462)

---

### ItemOrItemArray

Ƭ **ItemOrItemArray**<`T`\>: `T` \| `T`[]

#### Type parameters

| Name |
| :--- |
| `T`  |

#### Defined in

[types.ts:8](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L8)

---

### JsHandler

Ƭ **JsHandler**: (`rawSource`: `string`, `set`: `Set`<`string`\>, `options?`: [`CreateJsHandlerOptions`](#createjshandleroptions)) => [`JsHandlerResult`](#jshandlerresult)

#### Type declaration

▸ (`rawSource`, `set`, `options?`): [`JsHandlerResult`](#jshandlerresult)

##### Parameters

| Name        | Type                                                |
| :---------- | :-------------------------------------------------- |
| `rawSource` | `string`                                            |
| `set`       | `Set`<`string`\>                                    |
| `options?`  | [`CreateJsHandlerOptions`](#createjshandleroptions) |

##### Returns

[`JsHandlerResult`](#jshandlerresult)

#### Defined in

[types.ts:428](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L428)

---

### JsHandlerReplaceResult

Ƭ **JsHandlerReplaceResult**: `Object`

#### Type declaration

| Name   | Type        |
| :----- | :---------- |
| `code` | `string`    |
| `map?` | `SourceMap` |

#### Defined in

[types.ts:46](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L46)

---

### JsHandlerResult

Ƭ **JsHandlerResult**: [`JsHandlerReplaceResult`](#jshandlerreplaceresult) \| `GeneratorResult`

#### Defined in

[types.ts:48](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L48)

---

### RequiredStyleHandlerOptions

Ƭ **RequiredStyleHandlerOptions**: \{ `cssInjectPreflight?`: `InjectPreflight` ; `escapeMap?`: `Record`<`string`, `string`\> ; `isMainChunk`: `boolean` } & `Pick`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), `"cssPreflightRange"` \| `"cssChildCombinatorReplaceValue"` \| `"replaceUniversalSelectorWith"` \| `"injectAdditionalCssVarScope"` \| `"cssSelectorReplacement"`\>

#### Defined in

[types.ts:25](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L25)

### LoadedPostcssOptions

`LoadedPostcssOptions` 是 `postcss-load-config` 导出的 `Result` 类型去掉 `file` 字段后再取 `Partial`。在插件内部用于接收已经过 `postcss-load-config` 解析的运行时配置，例如自定义插件、语法语义等设置。

#### 定义

```ts
type LoadedPostcssOptions = Partial<Omit<Result, 'file'>>
```

#### 定义于

[packages/postcss/src/types.ts:14](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L14)

### PresetEnvOptions

`PresetEnvOptions` 直接复用自 `postcss-preset-env` 的 `pluginOptions`，用于控制 `stage`、`browsers`、`features` 等行为。传入该类型可以在保持 Docusaurus 生成文档一致的同时，自由扩展 CSS 预处理特性。

#### 定义

```ts

```

#### 定义于

[packages/postcss/src/types.ts:8](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L8)

### CssCalcOptions

`CssCalcOptions` 基于 `@weapp-tailwindcss/postcss-calc` 的 `PostCssCalcOptions` 扩展而来，并额外提供 `includeCustomProperties`，用于声明哪些自定义属性需要参与 `calc` 计算或在输出中保留。

#### 定义

```ts
interface CssCalcOptions extends PostCssCalcOptions {
  includeCustomProperties?: (string | RegExp)[]
}
```

#### 定义于

[packages/postcss/src/types.ts:45](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L45)

## Functions

### UnifiedViteWeappTailwindcssPlugin

▸ **UnifiedViteWeappTailwindcssPlugin**(`options?`): `Plugin` \| `undefined`

#### Parameters

| Name      | Type                                                     |
| :-------- | :------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md) |

#### Returns

`Plugin` \| `undefined`

**`Name`**

UnifiedViteWeappTailwindcssPlugin

**`Description`**

uni-app vite vue3 版本插件

**`Link`**

https://tw.icebreaker.top/docs/quick-start/frameworks/uni-app-vite

#### Defined in

[vite/index.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/vite/index.ts#L17)

---

### createPlugins

▸ **createPlugins**(`options?`): `Object`

#### Parameters

| Name      | Type                                                     |
| :-------- | :------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md) |

#### Returns

`Object`

| Name            | Type              |
| :-------------- | :---------------- |
| `transformJs`   | () => `Transform` |
| `transformWxml` | () => `Transform` |
| `transformWxss` | () => `Transform` |

**`Name`**

weapp-tw-gulp

**`Description`**

gulp版本weapp-tw插件

**`Link`**

https://tw.icebreaker.top/docs/quick-start/frameworks/native

#### Defined in

[gulp/index.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/gulp/index.ts#L17)

---

## Interface: IArbitraryValues

## Properties

### allowDoubleQuotes

• `Optional` **allowDoubleQuotes**: `boolean`

是否允许在类名里，使用双引号。
建议不要开启，因为有些框架，比如 `vue3` 它针对有些静态模板会直接编译成 `html` 字符串，此时开启这个配置很有可能导致转义出错

**`Example`**

```html
<!-- 开启前默认只允许单引号 -->
<view class="after:content-['对酒当歌，人生几何']"></view>
<!-- 开启后 -->
<view class="after:content-[\"对酒当歌，人生几何\"]"></view>
```

**`Default`**

`false`

#### Defined in

[types.ts:114](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L114)

---

## Interface: IBaseWebpackPlugin

## Implemented by

- [`UnifiedWebpackPluginV5`](../classes/UnifiedWebpackPluginV5.md)

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

#### Defined in

[types.ts:488](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L488)

---

### apply

• **apply**: (`compiler`: `any`) => `void`

#### Type declaration

▸ (`compiler`): `void`

##### Parameters

| Name       | Type  |
| :--------- | :---- |
| `compiler` | `any` |

##### Returns

`void`

#### Defined in

[types.ts:490](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L490)

---

### options

• **options**: `Required`<`Omit`<[`UserDefinedOptions`](UserDefinedOptions.md), `"customReplaceDictionary"` \| `"supportCustomLengthUnitsPatch"` \| [`GlobOrFunctionMatchers`](../#globorfunctionmatchers)\> & \{ `cssMatcher`: (`name`: `string`) => `boolean` ; `htmlMatcher`: (`name`: `string`) => `boolean` ; `jsMatcher`: (`name`: `string`) => `boolean` ; `mainCssChunkMatcher`: (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean` ; `wxsMatcher`: (`name`: `string`) => `boolean` } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](../#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](../#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: `false` \| [`ILengthUnitsPatchOptions`](ILengthUnitsPatchOptions.md) ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](ITemplateHandlerOptions.md)) => `string` }\>

#### Defined in

[types.ts:487](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L487)

---

## Interface: ICommonReplaceOptions

## Hierarchy

- **`ICommonReplaceOptions`**

  ↳ [`ITemplateHandlerOptions`](ITemplateHandlerOptions.md)

## Properties

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Defined in

[types.ts:442](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L442)

---

### keepEOL

• `Optional` **keepEOL**: `boolean`

#### Defined in

[types.ts:441](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L441)

---

## Interface: ILengthUnitsPatchDangerousOptions

## Properties

### destPath

• `Optional` **destPath**: `string`

#### Defined in

[types.ts:81](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L81)

---

### gteVersion

• `Optional` **gteVersion**: `string`

#### Defined in

[types.ts:77](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L77)

---

### lengthUnitsFilePath

• `Optional` **lengthUnitsFilePath**: `string`

#### Defined in

[types.ts:78](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L78)

---

### overwrite

• `Optional` **overwrite**: `boolean`

#### Defined in

[types.ts:80](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L80)

---

### packageName

• `Optional` **packageName**: `string`

#### Defined in

[types.ts:76](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L76)

---

### variableName

• `Optional` **variableName**: `string`

#### Defined in

[types.ts:79](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L79)

---

## Interface: ILengthUnitsPatchOptions

**`Deprecated`**

## Properties

### basedir

• `Optional` **basedir**: `string`

#### Defined in

[types.ts:91](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L91)

---

### dangerousOptions

• `Optional` **dangerousOptions**: [`ILengthUnitsPatchDangerousOptions`](ILengthUnitsPatchDangerousOptions.md)

#### Defined in

[types.ts:90](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L90)

---

### paths

• `Optional` **paths**: `string`[]

#### Defined in

[types.ts:89](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L89)

---

### units

• **units**: `string`[]

#### Defined in

[types.ts:88](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L88)

---

## Interface: IPropValue

## Properties

### prop

• **prop**: `string`

#### Defined in

[types.ts:13](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L13)

---

### value

• **value**: `string`

#### Defined in

[types.ts:14](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L14)

---

## Interface: ITemplateHandlerOptions

## Hierarchy

- [`ICommonReplaceOptions`](ICommonReplaceOptions.md)

  ↳ **`ITemplateHandlerOptions`**

## Properties

### customAttributesEntities

• `Optional` **customAttributesEntities**: [`ICustomAttributesEntities`](../#icustomattributesentities)

#### Defined in

[types.ts:447](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L447)

---

### disabledDefaultTemplateHandler

• `Optional` **disabledDefaultTemplateHandler**: `boolean`

#### Defined in

[types.ts:456](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L456)

---

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Overrides

[ICommonReplaceOptions](ICommonReplaceOptions.md).[escapeMap](ICommonReplaceOptions.md#escapemap)

#### Defined in

[types.ts:451](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L451)

---

### inlineWxs

• `Optional` **inlineWxs**: `boolean`

#### Defined in

[types.ts:453](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L453)

---

### jsHandler

• `Optional` **jsHandler**: [`JsHandler`](../#jshandler)

#### Defined in

[types.ts:454](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L454)

---

### keepEOL

• `Optional` **keepEOL**: `boolean`

#### Inherited from

[ICommonReplaceOptions](ICommonReplaceOptions.md).[keepEOL](ICommonReplaceOptions.md#keepeol)

#### Defined in

[types.ts:441](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L441)

### quote

• `Optional` **quote**: `null` \| `string`

#### Defined in

[types.ts:457](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L457)

---

### runtimeSet

• `Optional` **runtimeSet**: `Set`<`string`\>

#### Defined in

[types.ts:455](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L455)

---

## Interface: InternalCssSelectorReplacerOptions

## Properties

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Defined in

[types.ts:38](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L38)

---

## Interface: InternalPatchResult

**`Description`**

InternalPatchResult

## Properties

### dataTypes

• `Optional` **dataTypes**: `string`

#### Defined in

[types.ts:497](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L497)

---

### plugin

• `Optional` **plugin**: `string`

#### Defined in

[types.ts:499](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L499)

---

### processTailwindFeatures

• `Optional` **processTailwindFeatures**: `string`

#### Defined in

[types.ts:498](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L498)

---

## Interface: RawSource

## Properties

### end

• **end**: `number`

#### Defined in

[types.ts:67](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L67)

---

### raw

• **raw**: `string`

#### Defined in

[types.ts:68](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L68)

---

### source

• `Optional` **source**: `string`

#### Defined in

[types.ts:70](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L70)

---

### start

• **start**: `number`

#### Defined in

[types.ts:66](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L66)

---

## Interface: UserDefinedOptions

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

**`Description`**

使用的框架类型(uni-app,taro...)，用于找到主要的 `css bundle` 进行转化，这个配置会影响默认方法 `mainCssChunkMatcher` 的行为，不传会去猜测 `tailwindcss css var inject scope` 的位置

#### Defined in

[types.ts:284](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L284)

---

### arbitraryValues

• `Optional` **arbitraryValues**: [`IArbitraryValues`](IArbitraryValues.md)

**`Description`**

针对 tailwindcss arbitrary values 的一些配置

#### Defined in

[types.ts:301](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L301)

---

### cssChildCombinatorReplaceValue

• `Optional` **cssChildCombinatorReplaceValue**: `string` \| `string`[]

**`Description`**

用于控制 tailwindcss 子组合器的生效标签范围, 这里我们用一个例子来说明这个配置是干啥用的.

我们布局的时候往往会使用 `space-x-4`
那么实际上会生成这样的css选择器:

```css
.space-x-4>:not([hidden])~:not([hidden]){}
```

然而很不幸，这个选择器在小程序中是不支持的，写了会报错导致编译失败。
所以出于保守起见，我把它替换为了：

```css
.space-x-4>view + view{}
```

这同时也是默认值, 而这个选项就允许你进行自定义子组合器的行为

你可以传入一个 字符串，或者字符串数组

1. 传入字符串数组,比如 `['view','text']` 生成:

```css
.space-y-4>view + view,text + text{}
```

2. 传入一个字符串，此时行为变成了整个替换，比如 `'view,text,button,input ~ view,text,button,input'` 生成:

```css
.space-y-4>view,text,button,input ~ view,text,button,input{}
```

**`Default`**

```ts
'view + view'
```

#### Defined in

[types.ts:329](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L329)

---

### cssMatcher

• `Optional` **cssMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配 `wxss` 等等样式文件的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:125](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L125)

---

### cssPreflight

• `Optional` **cssPreflight**: [`CssPreflightOptions`](../#csspreflightoptions)

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/7>

**`Description`**

在所有 view节点添加的 css 预设，可根据情况自由的禁用原先的规则，或者添加新的规则。 详细用法如下:

```js
// default 默认:
cssPreflight: {
'box-sizing': 'border-box',
'border-width': '0',
'border-style': 'solid',
'border-color': 'currentColor'
}
// result
// box-sizing: border-box;
// border-width: 0;
// border-style: solid;
// border-color: currentColor

// case 禁用所有
cssPreflight: false
// result
// none

// case 禁用单个属性
cssPreflight: {
'box-sizing': false
}
// border-width: 0;
// border-style: solid;
// border-color: currentColor

// case 更改和添加单个属性
cssPreflight: {
'box-sizing': 'content-box',
'background': 'black'
}
// result
// box-sizing: content-box;
// border-width: 0;
// border-style: solid;
// border-color: currentColor;
// background: black
```

#### Defined in

[types.ts:178](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L178)

---

### cssPreflightRange

• `Optional` **cssPreflightRange**: `"view"` \| `"all"`

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/pull/62>

**`Description`**

全局`dom`选择器，只有在这个选择器作用范围内的`dom`会被注入 `cssPreflight` 的变量和默认样式。默认为 `'view'` 即只对所有的 `view` 和伪元素生效，想要对所有的元素生效，可切换为 `'all'`,此时需要自行处理和客户端默认样式的冲突

#### Defined in

[types.ts:184](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L184)

---

### cssSelectorReplacement

• `Optional` **cssSelectorReplacement**: `Object`

#### Type declaration

| Name         | Type                | Description               |
| :----------- | :------------------ | :------------------------ |
| `root?`      | `string` \| `false` | **`Default`** `ts 'page'` |
| `universal?` | `string` \| `false` | **`Default`** `ts 'view'` |

#### Defined in

[types.ts:410](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L410)

---

### customAttributes

• `Optional` **customAttributes**: [`ICustomAttributes`](../#icustomattributes)

**`Description`**

**这是一个重要的配置!**

它可以自定义`wxml`标签上的`attr`转化属性。默认转化所有的`class`和`hover-class`，这个`Map`的 `key`为匹配标签，`value`为属性字符串或者匹配正则数组。

如果你想要增加，对于所有标签都生效的转化的属性，你可以添加 `*`: `(string | Regexp)[]` 这样的键值对。(`*` 是一个特殊值，代表所有标签)

更复杂的情况，可以传一个 `Map<string | Regex, (string | Regex)[]>`实例。

假如你要把 `className` 通过组件的`prop`传递给子组件，又或者想要自定义转化的标签属性时，需要用到此配置，案例详见：[issue#129](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/129#issuecomment-1340914688),[issue#134](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/134#issuecomment-1351288238)

**`Example`**

```js
const customAttributes = {
// 匹配所有带 Class / class 相关的标签，比如 `a-class`, `testClass` , `custom-class` 里的值
'*': [ /[A-Za-z]?[A-Za-z-]*[Cc]lass/ ],
// 额外匹配转化 `van-image` 标签上的 `custom-class` 的值
'van-image': ['custom-class'],
'ice-button': ['testClass']
}
```

当然你可以根据自己的需求，定义单个或者多个正则/字符串。

甚至有可能你编写正则表达式，它们匹配的范围，直接包括了插件里自带默认的 `class`/`hover-class`，那么这种情况下，你完全可以取代插件的默认模板转化器，开启 [disabledDefaultTemplateHandler](/docs/api/options/general#disableddefaulttemplatehandler) 配置项,禁用默认的模版匹配转化器。

#### Defined in

[types.ts:251](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L251)

---

### customReplaceDictionary

• `Optional` **customReplaceDictionary**: `Record`<`string`, `string`\> \| `"simple"` \| `"complex"`

**`Description`**

自定义转化class名称字典，这个配置项用来自定义转化`class`名称字典,你可以使用这个选项来简化生成的`class`

插件中内置了`'simple'`模式和`'complex'`模式:

- `'simple'`模式: 把小程序中不允许的字符串，转义为**相等长度**的代替字符串，这种情况不追求转化目标字符串的一比一绝对等价，即无法从生成结果，反推原先的`class`
- `'complex'`模式: 把小程序中不允许的字符串，转义为**更长**的代替字符串，这种情况转化前后的字符串是等价的，可以从结果进行反推，缺点就是会生成更长的 `class` 导致 `wxml`和`wxss`这类的体积增大

当然，你也可以自定义，传一个 `Record<string, string>` 类型，只需保证转化后 css 中的 `class` 选择器，不会和自己定义的 `class` 产生冲突即可，示例见[dic.ts](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/blob/main/src/dic.ts)

**`Default`**

```ts
'simple'
```

#### Defined in

[types.ts:263](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L263)

### disabled

• `Optional` **disabled**: `boolean`

**`Description`**

是否禁用此插件，一般用于构建到多平台时使用

#### Defined in

[types.ts:196](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L196)

---

### disabledDefaultTemplateHandler

• `Optional` **disabledDefaultTemplateHandler**: `boolean`

**`Version`**

`^2.6.2`

**`Description`**

开启此选项，将会禁用默认 `wxml` 模板替换器，此时模板的匹配和转化将完全被 [`customAttributes`](/docs/api/options/important#customattributes) 接管，

此时你需要自己编写匹配之前默认 `class`/`hover-class`，以及新的标签属性的正则表达式`regex`

**`Default`**

```ts
false
```

#### Defined in

[types.ts:389](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L389)

---

### htmlMatcher

• `Optional` **htmlMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配 `wxml`等等模板进行处理的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:121](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L121)

---

### injectAdditionalCssVarScope

• `Optional` **injectAdditionalCssVarScope**: `boolean`

**`Version`**

`^2.6.0`

**`Description`**

是否注入额外的 `tailwindcss css var scope` 区域，这个选项用于这样的场景

比如 `taro vue3` 使用 [NutUI](https://nutui.jd.com), 需要使用 `@tarojs/plugin-html`，而这个插件会启用 `postcss-html-transform` 从而移除所有带 `*` 选择器

这会导致 `tailwindcss css var scope` 区域被移除导致一些样式，比如渐变等等功能失效

这种场景下，启用这个选项会再次重新注入整个 `tailwindcss css var scope`

**`Default`**

```ts
false
```

#### Defined in

[types.ts:373](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L373)

---

### inlineWxs

• `Optional` **inlineWxs**: `boolean`

**`Experiment`**

实验性质，有可能会改变

**`Description`**

是否转义 `wxml` 中内联的 `wxs`

> tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效

**`Example`**

```html
<!-- index.wxml -->
<wxs module="inline">
// 我是内联wxs
// 下方的类名会被转义
var className = "after:content-['我是className']"
module.exports = {
 className: className
}
</wxs>
<wxs src="./index.wxs" module="outside"/>
<view><view class="{{inline.className}}"></view><view class="{{outside.className}}"></view></view>
```

**`Default`**

```ts
false
```

#### Defined in

[types.ts:359](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L359)

---

### jsEscapeStrategy

• `Optional` **jsEscapeStrategy**: `"regenerate"` \| `"replace"`

**`Version`**

`^2.7.0`

**`Description`**

js 字面量以及模板字符串的转义替换模式

- `regenerate` 模式，为需要转义的字面量，重新生成相同语义的字符串, （默认的传统模式）
- `replace` 模式，为在原版本字符串上直接精准替换, (`2.7.0+` 新增)

如果用一个比喻来形容，那么 `regenerate` 类似于创造一个双胞胎，而 `replace` 模式就类似于一把精准的手术刀

> `replace` 模式已经在 `2.8.0` 版本中，成为默认模式，另外使用这个模式之后，生成相关的参数，比如 `minifiedJs` 就会失效了。

**`Default`**

```ts
'regenerate'
```

#### Defined in

[types.ts:402](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L402)

---

### jsMatcher

• `Optional` **jsMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配编译后 `js` 文件进行处理的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:129](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L129)

---

### jsPreserveClass

• `Optional` **jsPreserveClass**: (`keyword`: `string`) => `undefined` \| `boolean`

#### Type declaration

▸ (`keyword`): `undefined` \| `boolean`

##### Parameters

| Name      | Type     |
| :-------- | :------- |
| `keyword` | `string` |

##### Returns

`undefined` \| `boolean`

**`Version`**

`^2.6.1`

**`Description`**

当 `tailwindcss` 和 `js` 处理的字面量撞车的时候，配置此选项可以用来保留js字面量，不进行转义处理。返回值中，想要当前js字面量保留，则返回 `true`。想要转义则返回 `false/undefined`

**`Default`**

保留所有带 `*` js字符串字面量

#### Defined in

[types.ts:380](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L380)

---

### mainCssChunkMatcher

• `Optional` **mainCssChunkMatcher**: `string` \| `string`[] \| (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean`

**`Description`**

`tailwindcss css var inject scope` 的匹配方法,用于处理原始变量和替换不兼容选择器。可以不传，但是遇到某些 `::before/::after` 选择器注入冲突时，建议传入参数手动指定 css bundle 文件位置

#### Defined in

[types.ts:134](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L134)

### minifiedJs

• `Optional` **minifiedJs**: `boolean`

**`Description`**

是否压缩 js (`process.env.NODE_ENV` 为 `production` 时默认开启)

**`Default`**

```ts
process.env.NODE_ENV === 'production'
```

#### Defined in

[types.ts:290](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L290)

---

### onEnd

• `Optional` **onEnd**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

结束处理时调用

#### Defined in

[types.ts:222](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L222)

---

### onLoad

• `Optional` **onLoad**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

plugin apply 初调用

#### Defined in

[types.ts:206](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L206)

---

### onStart

• `Optional` **onStart**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

开始处理时调用

#### Defined in

[types.ts:210](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L210)

---

### onUpdate

• `Optional` **onUpdate**: (`filename`: `string`, `oldVal`: `string`, `newVal`: `string`) => `void`

#### Type declaration

▸ (`filename`, `oldVal`, `newVal`): `void`

##### Parameters

| Name       | Type     |
| :--------- | :------- |
| `filename` | `string` |
| `oldVal`   | `string` |
| `newVal`   | `string` |

##### Returns

`void`

**`Description`**

匹配成功并修改文件内容后调用

#### Defined in

[types.ts:218](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L218)

---

### replaceUniversalSelectorWith

• `Optional` **replaceUniversalSelectorWith**: `string` \| `false`

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/81>

**`Default`**

```ts
'view'
```

**`Description`**

把`css`中的全局选择器 **`*`** 替换为指定值，默认替换为 `'view'`，设置为 `false` 时不进行替换，此时小程序会由于不认识`*`选择器而报错

#### Defined in

[types.ts:191](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L191)

---

### supportCustomLengthUnitsPatch

• `Optional` **supportCustomLengthUnitsPatch**: `boolean` \| [`ILengthUnitsPatchOptions`](ILengthUnitsPatchOptions.md)

**`Deprecated`**

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110>

**`Description`**

自从`tailwindcss 3.2.0`对任意值添加了长度单位的校验后，小程序中的`rpx`这个`wxss`单位，由于不在长度合法名单中，于是被识别成了颜色，导致与预期不符，详见：[issues/110](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110)。所以这个选项是用来给`tailwindcss`运行时，自动打上一个支持`rpx`单位的补丁。默认开启，在绝大部分情况下，你都可以忽略这个配置项，除非你需要更高级的自定义。

> 目前自动检索存在一定的缺陷，它会在第一次运行的时候不生效，关闭后第二次运行才生效。这是因为 nodejs 运行时先加载好了 `tailwindcss` 模块 ，然后再来运行这个插件，自动给 `tailwindcss` 运行时打上 `patch`。此时由于 `tailwindcss` 模块已经加载，所以 `patch` 在第一次运行时不生效，`ctrl+c` 关闭之后，再次运行才生效。这种情况可以使用:

```diff
"scripts": {
+  "postinstall": "weapp-tw patch"
}
```

使用 `npm hooks` 的方式来给 `tailwindcss` 自动打 `patch`

#### Defined in

[types.ts:279](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L279)

---

### tailwindcssBasedir

• `Optional` **tailwindcssBasedir**: `string`

**`Version`**

`^2.9.3`

**`Description`**

用于指定路径来获取 tailwindcss 上下文，一般情况下不用传入，使用 linked / monorepo 可能需要指定具体位置，路径通常是目标项目的 package.json 所在目录

#### Defined in

[types.ts:425](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L425)

---

### wxsMatcher

• `Optional` **wxsMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Experiment`**

实验性质，有可能会改变

**`Description`**

各个平台 `wxs` 文件的匹配方法,可以设置为包括微信的 .wxs,支付宝的 .sjs 和 百度小程序的 .filter.js

> tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效

**`Default`**

```ts
()=>false
```

#### Defined in

[types.ts:337](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L337)

---

## 使用 arbitrary values


`arbitrary values` 是 `tailwindcss v3` 的重要更新内容，幸运的是你使用了本插件。

使得你可以使用 `tailwindcss v3` 强大的 `arbitrary values` 功能。

比如:

```html
<view :class="[flag?'bg-red-900':'bg-[#fafa00]']">bg-[#fafa00]</view>
<view :class="{'bg-[#098765]':flag===true}">bg-[#098765]</view>
<view class="p-[20px] -mt-2 !mb-[-20px] ">p-[20px] -mt-2 mb-[-20px] margin的jit 不能这么写 -m-[20px]</view>
<view class="space-y-[1.6rem]">
  <view class="w-[300rpx] text-black text-opacity-[0.19]">w-[300rpx] text-black text-opacity-[0.19]</view>
  <view class="min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]">min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]</view>
  <view class="max-w-[300rpx] min-h-[100px] text-[#dddddd]">max-w-[300rpx] min-h-[100px] text-[#dddddd]</view>
  <view class="flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff]">Hello</view>
  <view class="border-[10px] border-[#098765] border-solid border-opacity-[0.44]">border-[10px] border-[#098765] border-solid border-opacity-[0.44]</view>
  <view class="grid grid-cols-3 divide-x-[10px] divide-[#010101] divide-solid">
    <view>1</view>
    <view>2</view>
    <view>3</view>
  </view>
</view>
```

or `@apply`

```html
<template><view class="hello">world</view></template>
<style lang="scss">
.hello {
  @apply flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff] #{!important};
}
</style>
```

详见 [tailwindcss/using-arbitrary-values 章节](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values)

---

## js 中的精确转化与忽略


默认对所有 `jsx`、`js`、`wxml`、`wxss` 中出现的 `tailwindcss` 运行时工具类进行转化，如果不需要转化可以使用 `weappTwIgnore` 标识符来进行忽略:

例如:

```js
<view :class="classArray">classArray</view>

// weappTwIgnore 就是 String.raw ，所以它的结果就是后面字符串的结果
const weappTwIgnore = String.raw
const classArray = [
  'text-[30rpx]',
  weappTwIgnore`bg-[#00ff00]`
]

```

此时只有 `'text-[30rpx]'` 会被转化，`'bg-[#00ff00]'` 会被忽略。

> 默认情况下仅会忽略与 `weappTwIgnore` 有直接关系的标记模板，例如从包里导入后重命名、或在同一文件里一路别名过去的写法。简单的 `String.raw` 别名会继续参加转译，防止误杀。

如果需要自定义别名，可以包装一层函数并在配置里显式加入该别名，例如：

```js
const alias = (...args) => String.raw(...args)
// 在 ignoreTaggedTemplateExpressionIdentifiers 中加入 'alias'
```

或者直接使用 `ignoreTaggedTemplateExpressionIdentifiers` 配置追加其它标识符。

---

## weapp-tailwindcss 导出总览


> 本文根据 `packages/weapp-tailwindcss/package.json` 的 `exports` 字段整理，帮助你在不同框架/构建场景中快速定位合适的入口文件。

weapp-tailwindcss 同时提供 ESM 与 CommonJS 入口，并内置多个二级导出以适配 webpack、Vite、Gulp、Tailwind 宏等不同组合。下面按用途分类进行说明。

## 核心插件入口

| 导出路径 | 说明 | 典型用法 |
| --- | --- | --- |
| `weapp-tailwindcss` | 聚合入口：`createPlugins`、`UnifiedWebpackPluginV5`、`UnifiedViteWeappTailwindcssPlugin` 等常用工厂齐备 | `import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss'`
| `weapp-tailwindcss/webpack` | webpack@5 适配入口（uni-app CLI、mpx、原生小程序等） | `const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')`
| `weapp-tailwindcss/webpack4` | webpack@4 适配入口（旧版 Taro/uni-app 项目） | `import { UnifiedWebpackPluginV4 } from 'weapp-tailwindcss/webpack4'`
| `weapp-tailwindcss/vite` | Vite 插件入口（Taro Vite、weapp-vite 等） | `import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'`
| `weapp-tailwindcss/core` | 暴露 `createContext` 等底层 API，可自定义 transform 流程 | `import { createContext } from 'weapp-tailwindcss/core'`

## 配置、工具与周边

| 导出路径 | 说明 | 场景 |
| --- | --- | --- |
| `weapp-tailwindcss/defaults` | 默认插件配置、补丁行为等常量 | 查看/复用默认选项
| `weapp-tailwindcss/presets` | 官方预设集合（差异化策略、Tailwind 配置等） | 扩展或组合默认行为
| [`weapp-tailwindcss/reset`](./reset) | 内置默认 `button` reset，可通过 `buttonReset` 选项禁用或改写选择器 | `@plugin 'weapp-tailwindcss/reset';`
| `weapp-tailwindcss/types` | TypeScript 类型定义便捷入口 | `import type { UserDefinedOptions } from 'weapp-tailwindcss/types'`
| `weapp-tailwindcss/escape` | `replaceWxml`、`isAllowedClassName` 等字符串处理工具 | 单独处理模板/字符串时复用
| `weapp-tailwindcss/postcss-html-transform` | 针对 HTML/WXML 的 PostCSS 转换器 | 自定义 PostCSS 流程
| `weapp-tailwindcss/css-macro` | Tailwind CSS 宏工具（JS/TS） | 在代码中动态生成原子类
| `weapp-tailwindcss/css-macro/postcss` | 宏工具的 PostCSS 版本 | 构建期宏替换
| `weapp-tailwindcss/gulp` | Gulp 插件入口 | 传统 Gulp 构建链集成
| `weapp-tailwindcss/package.json` | 包元数据 | 读取版本号等信息

> 补充：如果你需要的是“可直接导入的静态 reset 样式资源”，请使用独立包 [`@weapp-tailwindcss/reset`](/docs/community/reset)，而不是这里的 `weapp-tailwindcss/reset` 插件入口。

## 样式资源

| 导出路径 | 说明 | 引用示例 |
| --- | --- | --- |
| `weapp-tailwindcss/index.css` (`weapp-tailwindcss/index`) | 默认 runtime 样式（==推荐直接引用==） | `@import 'weapp-tailwindcss/index.css';`
| `weapp-tailwindcss/preflight.css` (`weapp-tailwindcss/preflight`) | 小程序专用 Preflight | `@import 'weapp-tailwindcss/preflight.css';`
| `weapp-tailwindcss/theme.css` (`weapp-tailwindcss/theme`) | 主题变量定义 | `@import 'weapp-tailwindcss/theme.css';`
| `weapp-tailwindcss/utilities.css` (`weapp-tailwindcss/utilities`) | 原子类集合 | `@import 'weapp-tailwindcss/utilities.css';`
| `weapp-tailwindcss/with-layer.css` (`weapp-tailwindcss/with-layer`) | layer 版样式，适配 Tailwind v4 layer 写法 | `@import 'weapp-tailwindcss/with-layer.css';`
| `weapp-tailwindcss/uni-app-x.css` (`weapp-tailwindcss/uni-app-x`) | uni-app x 定制样式 | `@import 'weapp-tailwindcss/uni-app-x.css';`
| `weapp-tailwindcss/css` | 指向 `css/index.css`，兼容旧目录结构 | `@import 'weapp-tailwindcss/css';`

> ⚠️ 注意：部分构建工具（例如 `postcss-import`、mpx CLI）在解析裸包名 `weapp-tailwindcss` 时可能回退到 JS 入口（`dist/index.js`），并抛出 “Unknown word "use strict"”。请显式写成 `@import 'weapp-tailwindcss/index.css'`，或在本地创建中转 `app.css` 后再导入。

## 其他导出

- `weapp-tailwindcss/*`：保留通配符路径，兼容历史文件结构；建议优先使用上表列出的稳定入口。
- 所有 JS 模块同时提供 `import` 与 `require` 两种格式，TS 项目结合 `types` 入口即可获得完整声明。

想进一步了解各模块暴露的 API，可以查阅 [`weapp-tailwindcss` API 总览](../api/index.md) 或直接阅读对应类型定义与源码。

---

## 选项概览

该章节的详细配置已经迁移至 [API / 配置项文档](/docs/api/interfaces/UserDefinedOptions)。

- [允许的类名写法](/docs/options/arbitrary-values)
- [注释用法与忽略开关](/docs/options/comments)

如果你在升级过程中需要参考原先的配置写法，请参见上方链接。

---

## `weapp-tailwindcss/reset`


`weapp-tailwindcss/reset` 提供一组面向小程序生态的 reset 插件能力，默认会：

- 清除所有 `button` 的原生样式（padding / 颜色 / border 等），让它的表现和 `view` / `text` 一致；
- 将 `<image>` / `` 统一为 `display: block`，并限制为 `max-width: 100%`、`height: auto`。

你可以通过选项控制是否注入这些规则、改写选择器 / 声明，甚至追加自定义 reset。

> ℹ️ `weapp-tailwindcss/reset` 目前是兼容导出层，实际实现来自 `@weapp-tailwindcss/reset`。老项目可以继续使用原入口，新项目也可以直接从 `@weapp-tailwindcss/reset` 导入。

> ℹ️ 当你传入 `.class` / `#id` 作为选择器时，插件会自动转换为 `[class~="class"]` / `[id="id"]`，确保它们仍属于 base layer，不会破坏其他层级。

## 可用选项

- `preset?: 'minimal' | 'form' | 'content' | 'media' | 'all' | ResetPreset[]`
- `buttonReset?: false | ResetConfig`
- `imageReset?: false | ResetConfig`
- `inputReset?: false | ResetConfig`
- `textareaReset?: false | ResetConfig`
- `listReset?: false | ResetConfig`
- `navigatorReset?: false | ResetConfig`
- `videoReset?: false | ResetConfig`
- `extraResets?: ResetConfig[]`

```ts
interface ResetConfig {
  selectors?: string[]        // 支持元素 / 类名 / ID
  declarations?: Record<string, string | number | false>
  pseudo?: Record<string, string | number | false> // 注入到 ::after
}
```

设置为 `false` 即可关闭对应默认 reset；当提供类名 / ID 时会自动转换为 `[class~="foo"]` / `[id="bar"]`。

对于 `inputReset`、`textareaReset`、`listReset`、`navigatorReset`、`videoReset` 这类默认未开启的内置项，如果你直接传入配置对象，插件也会自动启用对应 reset，不必先额外声明 `preset`。

```ts
reset({
  inputReset: {
    selectors: ['.wx-reset-input'],
  },
  videoReset: {
    selectors: ['.wx-reset-video'],
  },
})
```

## preset

`preset` 用来快速启用一组内置 reset。默认不传时等价于 `minimal`，保持和旧版本一致，只注入 `button` 与 `image`。

- `minimal`：`button` + `image`
- `form`：`minimal` + `input` + `textarea`
- `content`：`minimal` + `ul/ol` + `navigator/a`
- `media`：`minimal` + `video`
- `all`：启用全部内置 reset

你也可以组合多个 preset：

```ts
reset({
  preset: ['content', 'media'],
})
```

## Tailwind CSS v3 用法

```ts title="tailwind.config.ts"

export default {
  plugins: [
    // 默认注入 button/image reset
    reset(),

    // 完全自定义
    reset({
      preset: 'form',
      buttonReset: {
        selectors: ['.wx-reset-btn', '#primary-btn'],
        declarations: {
          padding: '0',
          backgroundColor: 'transparent',
        },
        pseudo: {
          border: 'none',
        },
      },
      imageReset: {
        selectors: ['.wx-reset-image'],
        declarations: {
          display: 'inline-block',
          borderWidth: '0',
        },
      },
      listReset: {
        selectors: ['.wx-reset-list'],
      },
      extraResets: [
        {
          selectors: ['.wx-reset-view'],
          declarations: {
            display: 'block',
            borderWidth: '0',
          },
          pseudo: {
            borderColor: 'transparent',
          },
        },
      ],
    }),
  ],
}
```

关闭默认 reset：

```ts
reset({
  buttonReset: false,
  imageReset: false,
})
```

即使启用了 `preset`，你仍然可以通过把单项设置为 `false` 的方式精确关闭内置 reset：

```ts
reset({
  preset: 'all',
  listReset: false,
  videoReset: false,
})
```

## Tailwind CSS v4 用法

在入口 CSS 中通过 `@plugin` 注册即可：

```css title="app.css"
@plugin 'weapp-tailwindcss/reset';

@plugin 'weapp-tailwindcss/reset' ({
  preset: 'content',
  buttonReset: false,
  imageReset: {
    selectors: ['.wx-reset-image'],
    declarations: {
      display: 'inline-block',
    },
  },
  extraResets: [
    {
      selectors: ['.list-reset'],
      declarations: { listStyle: 'none', margin: '0', padding: '0' },
    },
  ],
});

@import 'tailwindcss/utilities';
```

同样可以通过 `buttonReset: false` / `imageReset: false` 精准控制需要的 reset。`preset` 负责批量开启内置规则，`extraResets` 允许你一次性追加多个自定义规则。

---

## 从 v1 迁移到 v2


在 `2.x` 版本中，可以把之前使用的 `webpack` 插件，全部更换为 `UnifiedWebpackPluginV5` 插件，不过 `vite` 插件的导出有一些小变化:

`1.x`:

```js

```

`2.x`:

```js
// UnifiedViteWeappTailwindcssPlugin 就是新的插件

```

另外新的 `UnifiedWebpackPluginV5` 可以直接从 `weapp-tailwindcss-webpack-plugin` 引入，同时在新的 `UnifiedWebpackPluginV5` 中，之前所有的配置项都被继承了过来，只需要用它直接替换原先插件即可。

另外不要忘记把:

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

添加进你的 `package.json` 里，然后清除原先的打包缓存之后重新打包运行。

---

## 从 v2 迁移到 v3


v3 版本相比于 v2, 主要是删去一些过时的功能，配置项，同时会改变插件的默认值，使得整体插件变得更易用，更容易安装
假如你没有用到什么复杂自定义配置，那么完全可以平滑升级上来。

## 配置项改动

### 删除的配置项

- 删去 `replaceUniversalSelectorWith` 选项，使用 `cssSelectorReplacement.universal` 来代替，后者参数覆盖前者
- 删去 `minifiedJs` 选项，现在完全遵从用户的配置，用户压缩就压缩，反之亦然
- 删去 `jsEscapeStrategy` 选项，现在默认只有一种模式 `replace`/ 不再提供 `regenerate` 模式
- 删去 `customReplaceDictionary` 的 `complex` 模式，只内置 `simple` 模式 (你如果还要 `complex` 模式 ,可以从 `@weapp-core/escape` 引入，再传入 `customReplaceDictionary` 配置项即可)
- `cssMatcher`/`htmlMatcher`/`jsMatcher`/ `mainCssChunkMatcher` / `wxsMatcher` 不再能够传入 `glob` 表达式(例如`**/*.html`)，现在都是传入一个方法: `(name: string) => boolean`。要兼容原先的 `glob` 表达式，你可以通过 `minimatch` 把 `glob` 表达式转化成正则来兼容原先的配置
- `cssPreflightRange` 只存在一种模式，为 `all`, 之前的 `view` 选项交给 `cssSelectorReplacement.universal` 进行托管

### 增加的配置项

- `rem2rpx` : 类型 `rem2rpx?: boolean | rem2rpxOptions`

rem 转 rpx 配置，默认 **不开启**，可传入配置项，配置项见 <https://www.npmjs.com/package/postcss-rem-to-responsive-pixel>
这个配置项代表插件内置了 `postcss-rem-to-responsive-pixel` ，不过默认不开启，传入一个 `true` 相当于传入配置:

```js
{
  // 32 意味着 1rem = 32rpx
  rootValue: 32,
  // 默认所有属性都转化
  propList: ['*'],
  // 转化的单位,可以变成 px / rpx
  transformUnit: 'rpx',
}
```

当然你也可以传入 `rem2rpxOptions` 这样一个 `object` 进行自定义

#### 为什么默认不开启？

1. 为了从 `2.x` 版本可以平滑的过渡到 `3.x`
2. 从我的视角看，内置 `postcss` 插件功能，虽然整体集成度上更高了，但是对其他开发者可能不是那么自由，比如在 `2.x` 时候，由于 `postcss-rem-to-responsive-pixel` 是外置的，所以开发者可以自由的决定它的加载顺序和加载逻辑，但是内置之后都是我决定的。不过内置好处也有，就是开箱即用

### 增强的配置项

- `cssChildCombinatorReplaceValue`, `cssSelectorReplacement.root`,`cssSelectorReplacement.universal` 现在都可以接受字符串数组了，它们可以自动展开，防止选择器格式化错误问题

### 修改的默认值

- `cssPreflightRange` 从 `'view'` 变为 `undefined`, 现在 `all` 的作用变成了在 `tailwindcss` 变量注入区域的选择器，添加一个 `:not(not)` 的选择器作为全局选择器的替代
- `cssSelectorReplacement.universal` 从 `'view'` 变为 `['view', 'text']`, 这意味着 `*` 选择器会被展开成 `view,text` 以及对应方式
- `cssChildCombinatorReplaceValue` 从 `'view + view'` 变为 `['view']`
- `replaceUniversalSelectorWith`,`jsEscapeStrategy`,`minifiedJs` 选项被删除，所以不再保留默认值

### 现在选项合并，数组默认行为变为覆盖，原先是合并

```js
const options = getOptions(input,defaults)
defaults: ['a','b'], input:['c']
// before:
options == ['a','b','c']
// after:
options == ['c']
```

<https://github.com/sonofmagic/weapp-tailwindcss/issues/259>

---

## 从 v3 迁移到 v4


<!-- :::warning -->
<!-- 由于 `tailwindcss@4` 改动较大，直接变成了一个样式预处理器，和 `sass` / `less` 类似。

目前 `weapp-tailwindcss@4` 版本并没有较好地兼容 `tailwindcss@4`,  -->

<!-- 请继续以 `weapp-tailwindcss@4` + `tailwindcss@3` 的方式使用

等待 `weapp-tailwindcss` 正式兼容改造的文档发布 (2025-02-12)
::: -->

`tailwindcss@4` 改动较大，直接变成了一个样式预处理器，和 `sass` / `less` 类似，所以你不应该让 `tailwindcss@4` 和 `sass`, `less` 一起使用。

所以关于这方面的改动会比较多, 可能你需要把很多 `.scss`,`.less` 文件后缀改成 `.css`

`v4` 版本相比于 `v3`, 影响功能的重大变动较少，假如你没有用到什么复杂自定义配置，那么完全可以平滑升级上来。

## 重大变更

1. 移除 `jsAstTool` 的 `ast-grep` 支持，现在全部使用 `babel` 进行 `ast` 处理，假如你使用了这个配置，你可以保持不动，或者你可以把它删掉。

## 特性更新

1. 添加 `@weapp-tailwindcss/merge` 包作为小程序版本的 `tailwind-merge`
1. 增加 `ignoreTaggedTemplateExpressionIdentifiers` 和 `ignoreCallExpressionIdentifiers` 配置，用于和 `@weapp-tailwindcss/merge` 结合起来使用
1. 在安装 `@weapp-tailwindcss/merge` 时自动设置 `ignoreCallExpressionIdentifiers` 为 `['twMerge', 'twJoin', 'cva']` 默认不进行转义里面的字面量
1. 更改 `cssChildCombinatorReplaceValue` 默认值从 `['view']` -> `['view', 'text']` 为了更好的小程序开发体验

## 重构

1. 移除 `@babel/generator` 依赖
2. 去除 `weapp-tailwindcss/postcss` 导出，代替可直接安装使用 `@weapp-tailwindcss/postcss`
3. 增加 `weapp-tailwindcss/escape` 来取代 `weapp-tailwindcss/replace`, `weapp-tailwindcss/replace` 导出被移除
4. 项目 `monorepo` 区分包
5. 项目打包方式从 `rollup` 变为 `tsup`

## pnpm@10.x

假如你已经升级到了 `pnpm@10.x`，安装依赖后需要执行 `pnpm approve-builds weapp-tailwindcss` 将其加入 `onlyBuiltDependencies`，以便 `postinstall` 等 `npm hook` 能正常运行

---

## css 中使用 @apply 警告问题


## 解决方案

我们以 `vscode` 为例

1. 创建 `.vscode` 目录

然后在目录下创建 `settings.json` 和 `tailwind.json`

2. 修改 `settings.json` 添加

```jsn
{
  "css.customData": [".vscode/tailwind.json"]
}
```

3. 修改 `tailwind.json`

````json
{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@tailwind",
      "description": "Use the `@tailwind` directive to insert Tailwind's `base`, `components`, `utilities` and `screens` styles into your CSS.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#tailwind"
        }
      ]
    },
    {
      "name": "@apply",
      "description": "Use the `@apply` directive to inline any existing utility classes into your own custom CSS. This is useful when you find a common utility pattern in your HTML that you’d like to extract to a new component.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#apply"
        }
      ]
    },
    {
      "name": "@responsive",
      "description": "You can generate responsive variants of your own classes by wrapping their definitions in the `@responsive` directive:\n```css\n@responsive {\n  .alert {\n    background-color: #E53E3E;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#responsive"
        }
      ]
    },
    {
      "name": "@screen",
      "description": "The `@screen` directive allows you to create media queries that reference your breakpoints by **name** instead of duplicating their values in your own CSS:\n```css\n@screen sm {\n  /* ... */\n}\n```\n…gets transformed into this:\n```css\n@media (min-width: 640px) {\n  /* ... */\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#screen"
        }
      ]
    },
    {
      "name": "@variants",
      "description": "Generate `hover`, `focus`, `active` and other **variants** of your own utilities by wrapping their definitions in the `@variants` directive:\n```css\n@variants hover, focus {\n   .btn-brand {\n    background-color: #3182CE;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#variants"
        }
      ]
    }
  ]
}
````

这样 `@apply` 就不会报错了。

## 参考文档

https://github.com/tailwindlabs/tailwindcss/discussions/5258

---

## 默认盒模型(box-sizing)问题


`Tailwindcss` 默认会把所有的元素的盒模型，设置为 `border-box`

但是一些组件库，比如 `wot-design-uni`，实现使用的是 `content-box` ，一切换到 `border-box` 高度塌陷了， 所以会导致部分显示效果错乱。

> `box-sizing: border-box;` 这行样式是在 'tailwindcss/base' 中的，所以你禁用这行代码，感觉上生效了，但是这样不是很好的解决方案。

假如你要从插件层面解决问题，只要做出如下修改:

```js
uvtw({
  // 添加这一行配置即可
  cssPreflight: {
    'box-sizing': false,
  },
}),
```

这样就可以把 `box-sizing` 这个样式给去掉，但是你这样就要去评估原先那些依赖盒模型的样式是否会受到影响：

比如 `w-2`, `h-4` 都是盒子模型潜在的影响。

## 参考文档

https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csspreflight

https://github.com/sonofmagic/weapp-tailwindcss/issues/604

---

## CSS 变量失效问题


## 问题的现象

在使用 `taro` 或者 `uni-app` 中，可能你会遇到 `CSS` 变量失效问题

具体表现，就是你在使用下列类名的时候，小程序的模拟器上，不会出来任何的背景颜色:

```jsx
<View className='h-14 bg-gradient-to-r from-cyan-500 to-blue-500'></View>
<View className='h-14 bg-gradient-to-r from-sky-500 to-indigo-500'></View>
<View className='h-14 bg-gradient-to-r from-violet-500 to-fuchsia-500'></View>
<View className='h-14 bg-gradient-to-r from-purple-500 to-pink-500'></View>
```

## 原因以及解决方案

导致这个的原因，是由于全局的 `tailwindcss` 变量丢失，没有注入进 `App` 引起的。参阅[什么是 `tailwindcss` 全局变量注入区域](#什么是全局-tailwindcss-变量注入区域)。

例如在 `taro` 中和 `@tarojs/plugin-html` 一起使用，就会出现这个问题，这是因为 `@tarojs/plugin-html` 把 `tailwindcss` 变量区域直接删除了。

遇到这样的问题，解决方案也很简单，只需要给插件传入 `injectAdditionalCssVarScope: true` 参数即可。

代码片段和配置详情详见[和 NutUI 一起使用](./use-with-nutui)。

## 设置成功后的效果

设置成功之后的效果如下所示，可以观察一下左侧的效果，和右下角的 `inspect` 面板作为参考

![小程序生效图片](./css-vars.jpg)

## 什么是全局 `tailwindcss` 变量注入区域

在你的 `app.wxss` 样式产物文件中（例如：`taro` 或 `uni-app` 的 `dist` 文件夹内），都有这样一块区域。

上面的这个问题，就是这块变量注入区域没了导致的。

```css
::before,::after {
  --tw-content: "";
}
view,text,::before,::after {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
  box-sizing: border-box;
  border-width: 0;
  border-style: solid;
  border-color: currentColor;
}
::backdrop {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
}
```

这块区域就是你 `@tailwind base;` 展开后, `tailwindcss` 注入的全局变量块。

丢失这块区域会导致 `bg-gradient-to-r` 这种依赖 `css` 变量的原子类失效。

---

## 组件外部样式类（externalClasses）的支持

:::warning 快速结论
如果在自定义组件里写了 `my-class="bg-[#fafa00] text-[40px]"`，但调试器里看到变成了 `my-class="bg- #fafa00  text- 40px"` 并导致样式失效，请在插件配置中为 `customAttributes` 显式声明 `my-class`。
:::

## 典型现象

在封装原生自定义组件时经常会用到外部样式类（`externalClasses`）。例如：

```js
/* custom-component.js */
Component({
  externalClasses: ['my-class'],
})
```

在页面里直接使用 `tailwindcss` 工具类：

```html
<custom-component my-class="bg-[#fafa00] text-[40px]" />
```

小程序开发者工具会把 `my-class` 中的样式拆开成 `bg- #fafa00  text- 40px`，最终导致样式全部失效。

## 根本原因

插件默认只会转译 `class` 和 `hover-class`。外部样式类属于自定义属性，如果没有配置 [`customAttributes`](/docs/api/options/important#customattributes)，就不会被识别处理。

## 解决方案

在插件选项里增加自定义属性的映射即可：

```js
customAttributes: {
  '*': ['my-class'],
}
```

- `*` 代表匹配所有标签，你也可以改成具体的标签名或正则表达式。
- 支持传入 `Object` 或 `Map`，用于灵活地映射标签与属性的关系。

:::tip 多个外部样式类
如果组件同时暴露 `['my-class', 'title-class']`，直接把它们都写进同一个数组即可。
:::

## 扩展阅读

- 微信官方文档：[外部样式类](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#外部样式类)
- 插件配置项说明：[customAttributes](/docs/api/options/important#customattributes)

> 使用正则进行自定义匹配标签时，需要传入一个 `Map`，其中正则作为 `key`，数组作为 `value`。

---

## Tailwindcss 格式化


## prettier 插件

> 这是官方提供的包，

使用并在 `prettier` 注册 [`prettier-plugin-tailwindcss`](https://www.npmjs.com/package/prettier-plugin-tailwindcss)

## eslint 插件

使用并在 `eslint` 注册 [`eslint-plugin-tailwindcss`](https://www.npmjs.com/package/eslint-plugin-tailwindcss)

---

## group 和 peer 使用限制


## group 使用注意事项

在 `tailwindcss` 中，我们常常会这样写:

```html

  <view class="bg-pink-400 group-hover:bg-yellow-400">
    group tapped
  </view>

```

这样在最外层的 `div` 进入 `hover` 状态时，内部的子元素中的 `group-hover` 就会生效，从而改变样式。

然而，在小程序中，伪类 `:hover` 是不起作用的，取而代之的是 `hover-class` 这样一个属性，所以这种情况我们可以这么写：

```html
<view class="group" hover-class="tapped">
  <view class="bg-pink-400 group-[.tapped]:bg-yellow-400">
    group tapped
  </view>
</view>
```

这样在 `group` 进入 `hover` 状态时，`bg-yellow-400` 就会生效了。

相关 issue：[#14](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template/issues/14)

## peer 使用注意事项

我们一般使用 `peer` 来标记一个元素，再使用各种 `peer-*` 来让它后续兄弟节点的样式生效。这些主要生成大量包含 `~` [后续兄弟选择器](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Subsequent-sibling_combinator) 的 `css` 代码。

然而很不幸，在小程序中 `~` 这个选择器非常容易报错，它前面只能跟 `class` 选择器，不能跟伪类，不然会报错:

```scss
// 报错
// .xxx:invalid~.xxx-invalid:visible {
//   visibility: visible;
// }
// 不报错
.xxx~.xxx-invalid:visible {
  visibility: visible;
}
```

所以你要么就不使用 `peer` 特性，如果需要此特性请使用内嵌 `class` 的方式来使用:

```html
<view>
  <view class="w-20 h-20 peer bg-gray-300" hover-class="tapped" />
  <view class="w-20 h-20 peer-[.tapped]:bg-red-400 bg-blue-400"></view>
</view>
```

> 前一个方块按压后进入 `hover` 状态 ，后面那个就变成红色。

## 出现 unexpected token "~" 错误

出现这个错误后，你应该把对应报错的相关 `peer`、`peer-*` 删掉，注意是删掉，请不要注释，因为 `tailwindcss` 中也会从注释中提取字符串，所以注释掉是没有效果的。

删掉之后，你需要重新启动一下你的应用（例如 `yarn dev:weapp`），不然导致错误的 `css` 还是会存在，导致项目崩溃。

---

## 常见问题


:::info 组件外部样式类必读
自定义组件使用 `externalClasses` 时样式被拆分？请先查看《[组件外部样式类（externalClasses）的支持](/docs/issues/externalClasses)》，按照文档里的 `customAttributes` 配置即可解决。
:::

## 为什么我更改了 class 保存重新打包的时候热更新失效？

[[#93](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/93)]

目前微信开发者工具会默认开启代码自动热重载 `compileHotReLoad` 功能，这个功能在原生开发中表现良好，但在 `uni-app` 和 `taro` 等的框架中，存在一定的问题，参见 [issues#37](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/37)，所以如果你遇到了此类问题，建议关闭 `compileHotReLoad` 功能。

## `disabled:opacity-50` 这类的 `tailwindcss` 工具类不生效?

这是由于微信小程序 `wxss` 选择器的原生限制，无法突破。参见 [issue#33](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/33)。

## `background-image` 为什么不能使用本地路径？

微信小程序在 `wxss` 中禁止 `background-image` 引用本地文件，解析时会直接报 `do-not-use-local-path` 错误。因此像 <code>bg-&#91;url('/images/homebg.png')&#93;</code> 这样的写法无法生效。请改用以下任一方式：

- 使用线上可访问的远程图片地址，例如 `bg-[url('https://example.com/bg.png')]`
- 将资源转成 `base64` 后内联到 `background-image`
- 改用 `<image>` 组件渲染背景效果

选择合适方案后再通过 `tailwindcss` 编写样式，即可避免编译报错。

## 和原生组件一起使用注意事项

假如出现原生组件引入报错的情况，可以参阅 [issue#35](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/35)，忽略指定目录下的文件，跳过插件处理，例如 `uni-app` 中的 `wxcomponents`。

如何更改？在传入的配置项 `cssMatcher`，`htmlMatcher` 这类配置，来过滤指定目录或文件。

## uni-app + Tailwind CSS v3 扫描 `src/uni_modules` 后生成异常 CSS

### 问题现象

当 `tailwind.config` 使用下面这种过宽的 `content` 配置：

```ts
content: ['./src/**/*.{html,js,ts,jsx,tsx,vue}']
```

并且项目里存在 `src/uni_modules/**/*` 第三方包时，Tailwind 可能扫描到依赖源码中的正则片段或示例文本，例如 `[a-zA-Z:_]`，并把它当成 arbitrary property class 提取。

在小程序场景下，再经过 `weapp-tailwindcss` 转译后，最终可能出现类似：

```css
._ba-zA-Z_c__B {
  a-z-a--z:;
}
```

这样的异常产物。

### 根因

这类问题的根因不是业务代码真的写了这个 class，而是 Tailwind v3 的内容提取器误扫了第三方目录中的源码、文档或构建产物。

### 推荐配置

请显式排除 `src/uni_modules`：

```ts title="tailwind.config.ts"
export default {
  content: [
    './index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
    '!./src/uni_modules/**/*',
  ],
}
```

### 最佳实践

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

## 编译到 h5 / app 注意事项

有些用户通过 `uni-app` 等跨端框架，不止开发成各种小程序，也开发为 `H5`，然而 `tailwindcss` 本身就兼容 `H5` 了。此时你需要更改配置，我们以 `uni-app` 为例:

```js
const isH5 = process.env.UNI_PLATFORM === "h5";
// vue3 版本构建到 app, UNI_PLATFORM 的值为 app
// vue2 版本为 app-plus
const isApp = process.env.UNI_PLATFORM === "app-plus";
const WeappTailwindcssDisabled = isH5 || isApp;

// 然后在 h5 和 app 环境下把 webpack plugin 和 postcss for weapp 给禁用掉
// 我们以 uni-app-vue3-vite 这个 demo为例
// vite.config.ts

// vite 插件配置
const vitePlugins = [uni(),uvtw({
  disabled: WeappTailwindcssDisabled
})];

export default defineConfig({
  plugins: vitePlugins
});

// 同理 postcss 配置
// 假如不起作用，请使用内联postcss
const plugins = [require('autoprefixer')(), require('tailwindcss')()];

if (!WeappTailwindcssDisabled) {
  plugins.push(
    require('postcss-rem-to-responsive-pixel')({
      rootValue: 32,
      propList: ['*'],
      transformUnit: 'rpx'
    })
  );
}

module.exports = {
  plugins
};
```

## 报错 TypeError: Cannot use 'in' operator to search for 'CallExpression' in undefined

遇到这个问题是由于 `babel` 相关的包之间的版本产生了冲突导致的，这种时候可以删除掉 `lock` 文件（`yarn.lock`、`pnpm-lock.yaml`、`package-lock.json`），然后重新安装即可。

## taro webpack5 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 为什么 space-y-1 这类写法不起作用?

相关 issue：[#108](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/108)

考虑到小程序的组件 `shadow root` 实现方式，默认情况下 `space` 这一类带有子选择器的，只对 `view` 元素生效。

即选择器变成了 `.space-y-1 > view + view`

这时候解决方案有 3 种：

- 组件外层套一层 `<view>` 元素。
- `virtualHost` 解决方案，在自定义组件中添加 `options: { virtualHost: true }` 即可解决此问题。
- [`cssChildCombinatorReplaceValue`](/docs/api/options/general#csschildcombinatorreplacevalue) 配置项

## 使用 uni-app vite vue 注册插件时，发行到 h5 环境出现: [plugin:vite-plugin-uni-app-weapp-tailwindcss-adaptor] 'import' and 'export' may appear only with 'sourceType: "module"' (1:0) 错误

解决方案：

```js
// 注意：打包成 h5 和 app 都不需要开启插件配置
const isH5 = process.env.UNI_PLATFORM === "h5";
// vue3 版本构建到 app, UNI_PLATFORM 的值为 app
// vue2 版本为 app-plus
const isApp = process.env.UNI_PLATFORM === "app-plus";
const WeappTailwindcssDisabled = isH5 || isApp;
const vitePlugins = [uni(), uvwt({
  disabled: WeappTailwindcssDisabled
})];
```

即 `h5` 环境和 `app` 环境都不开启我这个插件，因为本来这 2 个环境就是 `tailwindcss` 支持的环境，没必要开启插件转义。

## 使用 pnpm@8 插件注册失败问题

pnpm 8 这个版本改变了一些默认值，其中 `resolution-mode` 默认值变成了 `lowest-direct`。

这会导致所有的依赖，会被安装成你在 `package.json` 里注册的最低版本，这可能会造成一些问题。如何解决？

目录下创建一个 `.npmrc`，设置 `resolution-mode` 为 `highest`，然后重新安装，

或者，使用 `pnpm up -Li` 升级一下你 `package.json` 里的依赖包版本到最新即可。

## uni-app 在从v1升级到v2的过程中，如果使用了云函数相关功能，编译到小程序会出现问题

解决方案参见：<https://ask.dcloud.net.cn/question/170057>

相关 issue：[#74](https://github.com/sonofmagic/weapp-tailwindcss/issues/74#issuecomment-1573033475)

## uni-app vue2 中的 css 使用 @import 引入其他 css，导致在 `rpx` 在H5下不生效

需要添加并配置 `postcss-import`，参见 [issues/75](https://github.com/sonofmagic/weapp-tailwindcss/issues/75#issuecomment-1574592907)。

你可以参考仓库中的 `demo/uni-app-vue3-vite` 来进行配置。

## 为什么使用 taro 写 jsx，js 时候，转义不生效？

这是因为 [patch](/docs/quick-start/this-plugin) 方法没有生效，这个指令是用来在运行时暴露 `tailwindcss` 上下文的，只有暴露成功，我们写的 `js` 里的样式，才会变精准转义，否则就会出现在 `jsx` 里写 `className` 不生效的情况。

## monorepo 项目中 arbitrary values 写法无效？

这可能是由于 tailwindcss 包被提升，导致项目获取不到正确的 tailwind 上下文，有两种解决方案。

- 配置 [tailwindcssBasedir](https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#tailwindcssbasedir)

- 禁止 `tailwindcss` 包被提升，具体配置方法可以去查阅各包管理器的说明文档

---

## 写在 js 中的 tailwindcss 任意值失效


`weapp-tailwindcss` 是允许你在 `js` 中编写任意值的，而且 `weapp-tailwindcss` 会自动帮你做好任意值的转译。

比如:

```js title="src/pages/index/index.js"
const xs = {
  wrapper: 'px-[4px] h-[40px]',
}
```

那么在最终的产物中，编译结果会自动变为

```js title="dist/pages/index/index.js"
const xs = {
  wrapper: 'px-_4px_ h-_40px_',
}
```

但是你这个文件，必须被 `tailwindcss` 感知到，并从里面提取到这 `2` 个 `class`。`weapp-tailwindcss` 才能通过和 `tailwindcss` 的通信，来完成这 `2` 个 `class` 的转译。

所以你这个源文件必须在 `tailwindcss@3` 中的 `tailwind.config.js` 中被 `content` 配置包括。或者 `tailwindcss@4` 被 `@source` 包括到，那这个自动转译的流程才能走完。

否则就会出现 `js` 转译没有进行, 导致开发者工具中审查元素时，出现:

```html
<view class="px- 4px  h- 40px "></view>
```

这种类名被切断的情况。

## 解决方案

### tailwindcss@3

检查你的 `tailwind.config.js` 中的 `content`，确认你出现类名被切断的源文件，被 `content` 包括。

文档地址: https://v3.tailwindcss.com/docs/configuration#content

### tailwindcss@4

检查你的 `@source`，确认你出现类名被切断的源文件，被 `@source` 包括。

文档地址: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources

<!-- 因为 `tailwindcss` 和 `weapp-tailwindcss` 的转化规则 ，是根据你的源代码里提取出来的 `token` 决定的 -->

---

## 在 monorepo 中使用


在 `monorepo` 由于存在 `hoist` 机制，可能会导致 `weapp-tailwindcss` 和 `tailwindcss` 通信受阻，这时候需要显式的去指定 `tailwindcss` 的路径

这里我们以 `taro@4` 的配置 `config/index.ts` 配置为例

## Tailwindcss@3

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: UnifiedWebpackPluginV5,
          args: [
            {
              rem2rpx: true,
              // highlight-next-line
              tailwindcssBasedir: path.resolve(__dirname, '../'),
            },
          ],
        },
      },
    })
  },
}
```

## Tailwindcss@4

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: UnifiedWebpackPluginV5,
          args: [
            {
              rem2rpx: true,
              // highlight-next-line
              cssEntries: [
                // app.css 的路径
                path.resolve(__dirname, '../src/app.css'),
              ],
            },
          ],
        },
      },
    })
  },
}
```

使用这样的配置，就能在 `monorepo` 中使用了

---

## 生成样式只作用于view和text标签


在微信小程序中，`darkMode` 设置为 `class`/ `selector` 后，`dark:className` 类选择器在 `button` 上无效，看生成样式只作用于 `view` 和 `text` 标签

这是由于小程序是不接受 `*` 这样一个选择器的。

默认情况下， `weapp-tailwindcss` 会把 `*` 选择器转化成 `view,text` 的选择器

这个配置可以通过 `cssSelectorReplacement.universal` 进行更改，从而适配更多标签。

详见 [cssSelectorReplacement.universal 文档](/docs/api/options/important#cssselectorreplacement)

---

## 原生头条小程序使用 TailWindCSS


> 以下内容由使用 `weapp-tailwindcss` 的热心网友提供，十分感谢！

## 创建项目

创建项目 `test-miniapp`, 进入项目目录并初始化 `package.json`

```sh
cd test-miniapp
npm init -y
```

新建小程序开发目录 `src`，对应的小程序代码，生成目标代码目录为 `dist`

此时目录结构如下所示:

```
test-miniapp
-- src
-- dist
-- package.json
```

## 安装 gulp 及插件

- 本地安装 `gulp`

```sh
npm i -D gulp
```

- 安装 gulp 模块及插件

```sh
npm i -D gulp gulp-postcss gulp-plumber del@^6
```

## 安装与配置 tailwindcss

- 安装 tailwindcss

```sh
npm i -D tailwindcss@3 postcss autoprefixer
```

- 初始化 tailwindcss 配置文件

```sh
npx tailwindcss init
```

- 创建 `postcss.config.js` 并注册 `tailwindcss`

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    // 假如框架已经内置了 `autoprefixer`，可以去除下一行
    autoprefixer: {},
  }
}
```

- 配置 `tailwind.config.js`

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 不在 content 包括的文件内的 class，不会生成对应的 css 工具类
  content: ['./src/**/*.{ttml,js}'],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

- 代码引入 `tailwindcss`，打开 `src/app.ttss`

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

## 配置 vscode 插件

### Prettier - Code formatter

安装插件

```sh
npm i -D prettier prettier-plugin-tailwindcss
```

配置 `prettier.config.js`

```js
module.exports = {
  // 行尾加分号
  semi: false,
  // 使用单引号
  singleQuote: true,
  // 配置文件类型
  overrides: [
    {
      files: '*.ttml',
      options: { parser: 'html' },
    },
    {
      files: '*.ttss',
      options: { parser: 'css' },
    },
  ],
  plugins: ['prettier-plugin-tailwindcss'],
}
```

将小程序的文件包括进来，设置：`首选项->工作区->设置->扩展->Prettier->Prettier: Document Selectors`

```txt
**/*.ttml
**/*.ttss
```

- 字节小程序开发助手（微信小程序是这个：WXML - Language Service）

### Tailwind CSS IntelliSense

并配置：`首选项->工作区->设置->扩展->Tailwind CSS IntelliSense->Tailwind CSS: Include Languages`

```
项：ttml，值：html
```

### Gulp Tasks

- Gulp Tasks

  安装插件

  ```sh
  npm i -D weapp-tailwindcss-webpack-plugin
  ```

  配置 `gulpfile.js`，需要注意的事，在面板执行 `serve` 后，即使后来停止了任务，程序里的监听 `watch` 也不会停，使得后续再启动 `serve` 后，会有多个监听 `watch` 和多个监听处理程序 `watchHandler`，重复处理文件。所以停止后再启动 `serve`，应该关闭 `vscode` 后重新打开

  ```js
  const { src, dest, series, parallel, task, watch } = require('gulp')
  const postcss = require('gulp-postcss')
  const plumber = require('gulp-plumber')
  const path = require('path')
  const del = require('del')
  const tailwindcssGulp = require('weapp-tailwindcss-webpack-plugin/gulp')

  // 在 gulp 里使用, 先使用 postcss 转化 css, 触发 tailwindcss，然后转化 transformWxss，最后转化 transformJs, transformWxml
  const {
    transformJs,
    transformWxml: transformHtml,
    transformWxss: transformCss,
  } = tailwindcssGulp.createPlugins({
    rem2rpx: true,
  })

  const config = {
    srcDir: 'src',
    distDir: 'dist',
    cssExt: '.ttss',
    jsExt: '.js',
    htmlExt: '.ttml',
  }

  function transformCssFiles() {
    return src(`${config.srcDir}/**/*${config.cssExt}`)
      .pipe(plumber())
      .pipe(postcss())
      .pipe(transformCss())
      .pipe(dest(`${config.distDir}`))
  }

  function transformJsFiles() {
    return src(`${config.srcDir}/**/*${config.jsExt}`)
      .pipe(plumber())
      .pipe(transformJs())
      .pipe(dest(`${config.distDir}`))
  }

  function transformHtmlFiles() {
    return src(`${config.srcDir}/**/*${config.htmlExt}`)
      .pipe(plumber())
      .pipe(transformHtml())
      .pipe(dest(`${config.distDir}`))
  }

  function copyOtherFiles() {
    return src([
      `${config.srcDir}/**/*`,
      `!${config.srcDir}/**/*${config.cssExt}`,
      `!${config.srcDir}/**/*${config.jsExt}`,
      `!${config.srcDir}/**/*${config.htmlExt}`,
    ]).pipe(dest(`${config.distDir}`))
  }

  function promisify(task) {
    return new Promise((resolve, reject) => {
      if (task.destroyed) {
        resolve(undefined)
        return
      }
      task.on('finish', resolve).on('error', reject)
    })
  }

  // type 取值: changed, added, deleted
  async function watchHandler(type, file) {
    if (type == 'deleted') {
      await del([
        file.replace(
          `${config.srcDir}${path.sep}`,
          `${config.distDir}${path.sep}`
        ),
      ])
    } else {
      const extName = path.extname(file)
      switch (extName) {
        case config.cssExt:
          await promisify(transformCssFiles())
          break

        case config.jsExt:
          await promisify(transformCssFiles())
          await promisify(transformJsFiles())
          break

        case config.htmlExt:
          await promisify(transformCssFiles())
          await promisify(transformHtmlFiles())
          break

        default:
          await promisify(copyOtherFiles())
      }
    }
  }

  function watchTask() {
    const watcher = watch([`${config.srcDir}/**/*`])
    watcher
      .on('change', function (file) {
        console.log(`${file} is changed`)
        watchHandler('changed', file)
      })
      .on('add', function (file) {
        console.log(`${file} is added`)
        watchHandler('added', file)
      })
      .on('unlink', function (file) {
        console.log(`${file} is deleted`)
        watchHandler('deleted', file)
      })
  }

  function clean() {
    return del(config.distDir, { force: true })
  }

  const buildTasks = [
    transformCssFiles,
    transformJsFiles,
    transformHtmlFiles,
    copyOtherFiles,
  ]

  // 注册服务任务
  task('serve', series(...buildTasks, watchTask))

  // 注册清除任务
  task('clean', parallel(clean))
  ```

---

## rpx 任意值颜色或长度单位二义性与解决方案


## 这是一个什么问题？

在不使用 `weapp-tailwindcss` 的情况下，你直接写这样的 `rpx` 写法：

```html

```

最终它会生成这样的 `css`：

```css
.text-\[32rpx\] {
  color: 32rpx;
}
```

为什么 `rpx` 这个好端端的长度单位，会变成颜色呢？

原因在于 `rpx` 不是一个标准的 `W3C` 规定的 `CSS` 长度单位，这是微信小程序自己定的 `WXSS` 单位。

## 什么是 **二义性**?

`tailwindcss` 中有些原子类具有 **二义性**，比如:

- `text-[]`
- `border-[]`
- `bg-[]`
- `outline-[]`
- `ring-[]`

其中 `text-[]` 中的 `text-[16.16px]` 生成的 css 是 `font-size: 16.16px;`, 而 `text-[#123456]` 生成的 css 是 `color: #123456;`;

这就是原子类的 **二义性**

---

而 `tailwindcss` 在针对具有**二义性**的任意值写法:

这些会去**校验括号**内的任意值，是否为有效的 `CSS` 长度单位！

如果为 `true`，则生成出长度单位的 `css` 节点，反之则生成出颜色单位的 `css` 节点:

```css
/* text-[16px] */
.text-\[16px\] {
    font-size: 16px
}
/* text-[#fafafa] */
.text-\[\#fafafa\] {
    --tw-text-opacity: 1;
    color: rgb(250 250 250 / var(--tw-text-opacity))
}
```

那么问题来了，`rpx` 在单位校验的时候，由于不认识这个单位，导致单位无效所有被分到了颜色组。

```css
/* text-[32rpx] */
.text-\[32rpx\] {
    --tw-text-opacity: 1;
    color: 32rpx;
}
```

所以造成了这个问题！那么如何解决呢？

## 目前插件的解决方案

目前，我做了一个解决方案，我在 `weapp-tailwindcss` 植入了一个逻辑，使得插件可以通过分析 `tailwindcss` 运行时代码，来打上支持 `rpx` 单位的补丁，使得 `tailwindcss` 支持这样的写法，生成出长度单位的 `css`。

这也是为什么要让大家去执行 `weapp-tw patch` 的原因。

这个解决方案，最新的 `3.x` 和 `4.x` 版本，都是有效的。

<!-- 然而，以后 `tailwindcss` 将会使用由 `rust` 编写的新引擎。

这时候这种 `hack` 方式将会失效，毕竟那种情况下都是二进制文件了！

那么为了预防这种可能出现的危机，我们应该怎么做呢？ -->

## 强制CSS单位的解决方案

我们可以在使用这些带有**二义性**的单位的时候，可以通过 `length` 或 `color` 这种的前缀来指定它应该是什么，例如：

```html
...
...
<!-- 变成下列的写法 -->
...
...
```

这样就通过指定的方式，直接跳过了长度单位校验，生成出长度单位的 `css` 了！

```css
.text-\[length\:22rpx\] {
    font-size: 22rpx
}
```

同样你可以使用这 2 个前缀来指定 `css` 变量的生成形式：

```html
<!-- 生成 font-size  -->
...

<!-- 生成 color -->
...
```

## 参见

- `tailwindcss` 中的[添加自定义样式](https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities)
- 相关 Issue：[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/110)、[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/109)

---

## `Tarojs` 中使用 `terser` 压缩代码


在 `taro` `webpack5` 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

## 现象

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

## 解决方案

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 配置参考

```ts title="config/index.ts"
{
  terser: {
    enable: true,
    config: {
      // 相关配置项
    },
  },
}
```

然后你想要在开发时，就生效，那就需要传入 `NODE_ENV=production` 环境变量，例如:

```json title="package.json"
{
  "scripts":{
    "dev:weapp": "cross-env NODE_ENV=production npm run build:weapp -- --watch",
  }
}
```

`cross-env` 没有安装的可以安装一下

---

## H5 端原生 toast 样式偏移问题


在使用 `tailwindcss` 的时候，编译到 `h5` 平台，使用 `uni.toast` / `taro.toast` 时，出现下列的效果

![](./toast-svg-bug.jpg)

`tailwindcss` 的 `base` 中的 `preflight` 影响这个 `uni.toast` 的样式

这是由于 `preflight.css` 中默认会添加下方的样式

```css
img,
svg,
video,
canvas,
audio,
iframe,
embed,
object {
  display: block; /* 1 */
  vertical-align: middle; /* 2 */
}
```

这导致了 `svg` 变成了 `display: block;` 的状态

解决方案也非常的简单, 在 `app.wxss` 使用样式进行覆盖:

```scss
.uni-toast{
  svg {
    display: initial; // 重新初始化 uni-toast 里的样式进行覆盖 覆盖
  }
}
```

假如你使用的是 `uni-app`，那么还可以使用样式条件编译的方式来做:

```scss
/*  #ifdef  H5  */
svg {
  display: initial;
}
/*  #endif  */
```

---

## 和 NutUI 一起使用


`taro` 使用 [NutUI](https://nutui.jd.com) 的 `vue` 和 `react` 版本的共同注意点:

由于 [NutUI](https://nutui.jd.com) 必须要配合 `@tarojs/plugin-html` 一起使用。

然而 `@tarojs/plugin-html` 这个插件，默认情况下它会移除整个 `tailwindcss` 注入的 `css var` 区域块，这会造成所有 `tw-*` 相关变量找不到，导致样式大量挂掉的问题。例如（`drop-shadow-2xl`，`translate-1/2` 等样式）。

此时可以启用这个插件的 [`injectAdditionalCssVarScope`](/docs/api/options/important#injectadditionalcssvarscope) 配置项，把它设为 `true`，这能在插件内部启用功能，来重新注入整个 `tailwindcss` 的 `css` 中的 `var` 区域块( `tailwindcss@3` )。

按照初始的配置，只需要添加一行即可，示例如下：

```diff
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')

{
  mini: {
    webpackChain(chain, webpack) {
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              rem2rpx: true,
+             injectAdditionalCssVarScope: true
            }]
          }
        }
      })
    }
  }
}
```

## 可能有用但是过时的方案（部分 taro 版本有用）

~~需要去配置一下 `postcss-html-transform` 这个插件~~（实在找不到方法可以尝试一下）

```js
// config/index.js
config = {
  // ...
  mini: {
    // ...
    postcss: {
      htmltransform: {
        enable: true,
        // 设置成 false 表示 不去除 * 相关的选择器区块
        // 假如开启这个配置，它会把 tailwindcss 整个 css 的 var 区域块直接去除掉
        // 需要用 config 套一层，官方文档上是错的
        config: {
          removeCursorStyle: false,
        }
      },
    },
  },
}
```

## 参见

- [taro 官方文档](https://docs.taro.zone/docs/use-h5#插件-postcss-配置项)
- 相关 Issue：[#155](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/155)

---

## 和 Taroify 一起使用


`taro` 使用 [Taroify](https://taroify.github.io/taroify.com/) 的共同注意点:

由于 [Taroify](https://taroify.github.io/taroify.com/) 引入后，会导致 `tailwindcss` 的样式被覆盖，[Taroify](https://taroify.github.io/taroify.com/) 样式的优先级会高于 `tailwindcss`。

## 解决方案

### 修改Taroify引入方式

按照[Taroify](https://taroify.github.io/taroify.com/) 修改引入方式，将 `taroify` 引入方式改成按需引入

```bash npm2yarn
# 安装插件
npm i babel-plugin-import
```

修改Babel配置文件，修改组件和图标样式的引入方式为手动引入

```js
// babel.config.js
module.exports = {
  plugins: [
    [
      'import',
      {
        libraryName: '@taroify/core',
        libraryDirectory: '',
        // 这修改为false
        style: false,
        // style: false,
      },
      '@taroify/core',
    ],
    [
      'import',
      {
        libraryName: '@taroify/icons',
        libraryDirectory: '',
        camel2DashComponentName: false,
        // 这里修改为false
        style: false,
        // style: () => "@taroify/icons/style",
        customName: name => name === 'Icon' ? '@taroify/icons/van/VanIcon' : `@taroify/icons/${name}`,
      },
      '@taroify/icons',
    ],
  ],
}
```

### 修改引入样式顺序

修改根目录下的样式引入顺序，优先引入[Taroify](https://taroify.github.io/taroify.com/) 的样式，再引入Tailwindcss的样式

```tsx
// src/app.tsx

// ...

```

```scss
// src/app.scss

@use 'tailwindcss/base';
@use 'tailwindcss/components';
@use 'tailwindcss/utilities';
```

## 参见

- [Taroify 官方文档](https://taroify.github.io/taroify.com/)

---

## 和 wot-design-uni 一起使用



---

## v1 版本插件常见问题，使用最新版本插件无须参考


## 我在 `js` 里写了 `tailwindcss` 的任意值，为什么没有生效?

详见 [issue#28](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/28)

A: 因为这个插件，主要是针对, `wxss`,`wxml` 和 `jsx` 进行转义的，`js` 里编写的 `string` 是不转义的。如果你有这样的需求可以这么写:

```js

const cardsColor = reactive([
  replaceJs('bg-[#4268EA] shadow-indigo-100'),
  replaceJs('bg-[#123456] shadow-blue-100')
])
```

> 你不用担心把代码都打进来导致体积过大，我在 'weapp-tailwindcss-webpack-plugin/replace' 中，只暴露了2个方法，代码体积 1k左右，esm格式。

## replaceJs 跨端注意点

就是在常见问题中的 `replaceJs` 这个方法原先是为小程序平台设计的，假如你一份代码，需要同时编译到小程序和 `h5` 平台，可以参考如下的封装：

```js
// util.js

// uni-app 的条件编译写法
export function replaceClass(str) {
  // #ifdef H5
  return str
  // #endif
  return replaceJs(str)
}
// or 环境变量判断
export function replaceClass(str) {
  // 需要根据自己目标平台自定义，这里仅仅给一些思路
  if(process.env.UNI_PLATFORM === 'h5'){
    return str
  }
  return replaceJs(str)
}

// then other.js
const cardsColor = reactive([
  replaceClass('bg-[#4268EA] shadow-indigo-100'),
  replaceClass('bg-[#123456] shadow-blue-100')
])
```

这样就能在多端都生效了。

---

## AI 编程助手落地实施方案


> 你会得到：一套“能拍板、能试点、能复制”的落地方法（可治理、可控成本、可降级、可回滚）。\
> 更新时间：2025-12-29。计价说明：人民币换算按 1 USD = ¥7.2；价格与配额可能随时调整；以供应商官网与实际账单为准。

:::tip 这篇文档怎么读（别从头硬啃）

- 只想快速决策：先看「0 一页结论」→「5 座席设计」→「11 执行清单」。
- 要做试点落地：先看「6 路线图」→「7 仓库接入」→「8 日常 SOP」→「9 网络/账号/合规」。
- 研发负责人：0 / 5 / 6 / 11
- 平台与工具团队：6 / 7 / 8 / 9
- 安全合规：2 / 7 / 9
- 采购与财务：4 / 5 / 11
  :::

:::note 先记住三句话（后面所有细节都在解释这三句话）

1. 合规不清楚时，默认用国产把流程跑通。
2. 海外体验好不好，80% 取决于网络与代理是否“IDE + CLI + 登录”一致。
3. 成本能不能控住，靠“座席分层 + 预算上限 + 触顶降级”，不靠自觉。
   :::

---

## 0. 一页结论（先做决策，再做对比）

### 0.1 决策最短路径（建议按这个顺序拍板）

1. **合规边界**：哪些仓库/文件允许出境？是否必须审计留痕？（决定能不能用海外、能用到什么程度）
2. **网络能力**：是否能提供“IDE + CLI + 登录”同策略代理，并有备用出口与健康检查？（决定海外体验与成本是否可控）
3. **治理能力**：是否需要 SSO/团队配额/账单中心/审计？预算上限与告警责任人是谁？（决定能不能规模化）
4. **交付策略**：默认走低价/国产，高阶/海外按任务升级（而不是全员默认高阶）（决定 ROI 与成本波动）
5. **复制方式**：仓库接入模板与 SOP 能不能“一键复制”（决定试点能不能扩散）

### 0.2 快速分流（用一句话选出“主力方案”）

```mermaid
flowchart TD
  A[准备引入 AI 编程助手] --> B{代码出境/合规允许吗?}
  B -- 否/不确定 --> C["主力：国产（GLM/Qoder）先把规范、仓库分级、审计与 SOP 跑通"]
  B -- 是 --> D{海外网络与采购能闭环吗?}
  D -- 否 --> C
  D -- 是 --> E{是否要统一 IDE 作为工作台?}
  E -- 是 --> F["主力：Cursor（Business/Pro）国产作为兜底与降级"]
  E -- 否 --> G["主力：Claude Code / Codex / Gemini（CLI/插件）国产作为兜底与降级"]
  C --> H[按仓库分级 + 座席分层 + 预算上限 + 可回滚]
  F --> H
  G --> H
```

### 0.3 默认推荐（适用于大多数公司）

- **默认主力**：国产（GLM 或 Qoder）覆盖 70-85% 日常工作（补全、小改动、单测草稿、文档草稿）。
- **能力增强**：少量海外高阶座席（Cursor/Claude/Codex/Gemini）只用于“跨文件重构/疑难排查/核心模块审查/迁移方案”等高价值任务，并要求留痕与验收。
- **落地关键**：把“仓库分级 + 接入模板 + 预算上限 + 试点评估指标 + 回滚预案”当作一套工程系统，而不是发账号。

---

## 1. 我们要解决什么问题（落地目标与边界）

### 1.1 业务目标（建议写进 OKR）

- **效率**：提升日常编码速度（补全、重构、脚手架、查错、写测试、写文档）。
- **质量**：减少低级错误、提升可读性、一致性、单测覆盖率、PR 审查质量。
- **稳定**：在网络抖动/供应商限流/额度耗尽时，不影响核心交付（可降级/可回滚）。
- **合规**：明确哪些仓库/文件可用于 AI，上线前把出境、日志、留存、审计走通。
- **成本可控**：把“按量爆炸”风险降到最低（预算、告警、上限、分层座席）。

### 1.2 范围边界（避免项目失控）

- 本文仅讨论 **订阅型** AI 编程产品落地（IDE/CLI/Code Assist 套餐），**不单独设计“直接调用 API”的落地方案**。
- CI/CD 自动化如果要用 AI，优先使用供应商提供的 **官方能力**（如 PR Review、官方 CLI/插件），不建议自研“无限制 API 调用”。
- “AI 生成的代码”一律视为 **外部输入**：必须通过测试、代码审查、静态检查；不得直接上生产。

### 1.3 术语（让跨团队对齐）

- **补全**：Tab/Inline completion，一般成本最低、收益最高。
- **Chat / Agent**：对话式改代码、跨文件重构、读写文件、跑命令；成本更高、也更容易触碰合规边界。
- **座席分层**：并不是每个开发都用同样档位；核心成员/架构师/平台组用更高档位，其它人用基础档位。
- **仓库敏感度**：涉密/受限/合规严格的仓库与开源/公共仓库，允许的模型与策略不同。

---

## 2. 选型原则（先解决网络与合规）

### 2.1 两道门槛（Gate）：先能用、再用好

- **Gate A：合规与数据边界**（能不能用、能用到什么程度）
  - 代码出境是否允许？允许到什么仓库等级/目录/分支？
  - 是否必须可审计（谁在什么仓库用过什么能力）？日志如何留存、谁能访问？
- **Gate B：网络与采购闭环**（能不能稳定用、成本能不能控住）
  - 是否能提供“IDE + CLI + 登录”同策略代理，并有备用出口与健康检查？
  - 账号归属、统一账单、成本分摊、预算上限与告警责任人是否明确？

结论：**两道门槛都过了，海外能力才适合作为日常增强；任一没过关，优先按国产方案落地，把 SOP 与治理跑通，再引入海外。**

### 2.2 前提清单（要求“可验证”，避免口头承诺）

- 海外网络稳定：有健康检查数据（延迟/失败率）与备用出口；IDE 与 CLI 同策略；故障有降级预案。
- 合规已确认：书面结论明确出境范围；敏感目录黑名单可配置；审计与留存要求能落地。
- 采购支付可闭环：统一账单与成本中心；预算上限、告警阈值、责任人明确；离职回收流程明确。
- 用量能治理：团队配额/个人上限/触顶降级策略可执行（而不是“靠自觉”）。

### 2.3 怎么对比（前提满足后再对比）

| 维度       | 权重建议 | 评分要点（示例）                                 | 怎么验证（建议）                                |
| ---------- | -------- | ------------------------------------------------ | ----------------------------------------------- |
| 合规/数据  | 30%      | 出境边界、敏感路径屏蔽、审计日志、企业条款       | 合规书面结论 + 管理后台能力验证 + 试点抽样审计  |
| 可治理性   | 20%      | 团队配额、SSO、成员管理、账单中心、管理员策略    | 管理后台演示/截图 + 账号回收演练 + 账单样例     |
| 体验与产能 | 20%      | 补全质量、跨文件编辑、上下文、延迟、稳定性       | 用统一任务集试点对比（见 6.1/8.2 的场景）       |
| 成本与可控 | 15%      | 订阅单价、超额机制、是否易“按量爆炸”、是否可降级 | 账单实测 + 触顶降级演练 + 故障重试成本估算      |
| 集成能力   | 10%      | VS Code/JetBrains/CLI/PR Review 支持、可配置性   | 在 1-2 个真实仓库接入验证（模板/忽略规则/命令） |
| 供应商风险 | 5%       | 区域可用性、风控、服务 SLA、支付风险             | 历史可用性记录 + 支付与风控预案 + 可替代性评估  |

打分建议：每个方案 1-5 分，乘以权重；**先预设权重与通过条件**，试点后再复盘调整（避免“移动门槛”）。

### 2.4 选型评审要交付什么（避免只留一句“选 A”）

- 推荐结论：**主力方案 + 备份/降级方案**（故障/额度/风控时怎么切换）。
- 约束条件：仓库分级策略、允许能力（补全/对话/Agent）、审计与留存要求。
- 座席设计：分层（L1-L4）、升级流程、个人上限与团队配额、触顶降级策略。
- 落地计划：12 周里程碑（试点范围、复制范围、验收指标与 Go/No-Go）。
- 风险与缓解：合规、网络、供应商、成本波动、误改与质量风险，以及对应回滚方案。

---

## 3. 方案概览（我们讨论的 4 种可落地方案）

> 提示：如果网络/合规未就绪，先看 GLM/Qoder 两行，其它方案先当作备选。

| 方案                         | 定位                 | 典型个人月成本       | 典型团队 5 人月成本 | 关键依赖        | 适用结论                       |
| ---------------------------- | -------------------- | -------------------- | ------------------- | --------------- | ------------------------------ |
| Cursor                       | AI IDE（统一工作台） | ¥144（Pro）          | ~¥1,440（Business） | 海外网络/信用卡 | 体验优先、愿意统一 IDE 的团队  |
| Claude Code / Codex / Gemini | 海外订阅（插件/CLI） | ¥136-216             | ¥900-1,900          | 海外网络/信用卡 | 已有海外账单、偏 CLI/PR Review |
| GLM                          | 国产高刷新额度       | ¥100（Pro）          | ~¥500（Pro\*5）     | 无需代理        | 国内合规/报销友好、主力方案    |
| Qoder                        | 国产/混合路由        | ¥144-432（Pro/Pro+） | ~¥1,080（Teams\*5） | 国产为主        | 需要审计与团队管理、混合路由   |

---

## 4. 价格与额度（只保留对企业/大多数人有用的档位）

> 说明：下表用于预算与座席设计，不用于“攀比模型能力”。落地时真正影响成本的是：谁用高档位、是否有上限、网络稳定性（减少重复调用）、是否有明确的“默认低价模型策略”。

:::note 额度口径（先搞清楚你买的是什么）

不论是 Cursor、Kiro、GitHub Copilot 这类产品，本质上都是“使用 AI 的工作台/入口 + 各自最佳实践的工程化封装”，它们并不等同于某一个模型本身。

购买订阅时，你通常同时买到了两件事：

1. **工具能力**：IDE/插件/Agent 工作流、上下文管理、代码索引、团队治理等。
2. **供应商二次封装的模型调用额度**：对外表现为“对话次数/请求次数/快速请求/每周配额”等（而不是你能直接对账的 token 用量）。

优劣势也来自这里：

- **优势**：可以在不同模型之间切换/路由，按任务选“更强/更便宜/更稳”的模型；同时工具会给出默认提示词、工作流与防呆策略。
- **劣势**：你往往看不到真实 token 消耗与单次请求的边际成本；而按“对话/请求”计数时，**简单任务与复杂任务可能消耗同样 1 次额度**，导致成本预测与审计颗粒度变粗。

落地建议：预算口径按“座席 + 额度”做上限控制，同时用“默认低价模型 + 触顶降级 + 高阶任务审批/白名单”把波动压住。

:::

### 4.1 Cursor（官网可访问：已核实）

| 套餐     | 月付     | 年付折算 | 适用人群（企业落地建议）      | 人民币估算   |
| -------- | -------- | -------- | ----------------------------- | ------------ |
| Pro      | $20      | $200     | 普通开发（愿意用 Cursor IDE） | ¥144/月      |
| Pro+     | $60      | -        | 核心开发/架构师（重度 Agent） | ¥432/月      |
| Business | $40/用户 | -        | 需要 SSO/审计/团队配额的团队  | ¥288/用户/月 |
| Ultra    | $200     | -        | 极重度座席（专项、平台组）    | ¥1,440/月    |

来源：<https://cursor.com/pricing>（抓取到 Pro/Pro+/Ultra/Business）。

### 4.2 海外订阅（Claude Code / Codex / Gemini）

> 说明：海外产品的定价页可能因地区风控（如 Cloudflare）、登录态或动态渲染而不易自动抓取；以下仅保留“企业普遍会用的档位”与常见区间用于预算讨论。正式采购前请以供应商官网与合同条款再次核对。

| 方案               | 企业常用档位          | 常见价格（USD）                       | 适用人群                | 关键注意点                         |
| ------------------ | --------------------- | ------------------------------------- | ----------------------- | ---------------------------------- |
| Claude Code        | Pro / Teams           | $20 / $40/用户                        | CLI/Agent 重度团队      | 区域可用性、周配额、超额策略       |
| Codex / ChatGPT    | Team                  | ~$25/用户（年付）或 ~$30/用户（月付） | 跨团队通用              | 网页难抓取，采购前核对；设账单上限 |
| Gemini Coding Plan | Standard / Enterprise | $19 / $45                             | 有 PR Review 诉求的团队 | GCP 账单体系、日配额、账号治理     |

### 4.3 GLM Coding Plan（国产，主力）

| 套餐 | 月费 | 刷新周期  | 日可用（4-5 次刷新） | 企业落地建议      |
| ---- | ---- | --------- | -------------------- | ----------------- |
| Pro  | ¥100 | 每 5 小时 | 2400-3000 次         | 默认给大多数研发  |
| Max  | ¥400 | 每 5 小时 | 9600-12000 次        | 核心座席/批量任务 |

### 4.4 Qoder（国产/混合）

| 套餐            | 月付标价（USD） | 人民币估算   | 企业落地建议            |
| --------------- | --------------- | ------------ | ----------------------- |
| Pro             | $20             | ¥144/月      | 普通席位                |
| Pro+            | $60             | ¥432/月      | 核心席位/偶尔重任务     |
| Ultra           | $200            | ¥1,440/月    | 极重度席位（专项/平台） |
| Teams（按席位） | $30/用户        | ¥216/用户/月 | 需要审计/团队治理       |

说明：Qoder 定价接口会返回折扣字段（如 `discountedPrice` / `firstMonthPrice`），活动可能变化；预算建议按标价估算更稳。\
页面：<https://qoder.com/pricing>。\
接口（用于抓取标价/折扣字段）：<https://qoder.com/api/v1/products/pricing?productType=personal_subscription>、<https://qoder.com/api/v1/products/pricing?productType=enterprise_subscription&planTier=Teams>。

---

## 5. 企业级座席设计（怎么买才不浪费）

### 5.1 分层座席（推荐）

| 层级          | 占比建议 | 目标                       | 推荐档位（示例）                              |
| ------------- | -------- | -------------------------- | --------------------------------------------- |
| L1 普通开发   | 70-85%   | 日常补全+小改动            | GLM Pro / Qoder Pro / Cursor Pro              |
| L2 核心开发   | 10-20%   | 跨文件改造、重构、疑难排查 | Cursor Pro+ / GLM Max / Qoder Pro+            |
| L3 审查/架构  | 3-8%     | 评审、设计、复杂迁移       | Claude Code Teams / Cursor Business / GLM Max |
| L4 平台与专项 | 1-3%     | 规范化、模板化、内建流程   | Cursor Ultra（少量）/ GLM Max                 |

### 5.2 典型公司规模预算模板

> 这里的关键是“组合”，而不是单点选择。你可以把海外座席当作“稀缺资源”，像数据库/CI 一样管理。

#### 10 人团队（初期）

- 8 人：GLM Pro（8 \* ¥100 = ¥800/月）
- 2 人：Cursor Pro（2 \* ¥144 = ¥288/月）或 Qoder Pro（2 \* ¥144 = ¥288/月）
- 合计：约 ¥1,000/月（视组合而定）

#### 30 人团队（业务线）

- 24 人：GLM Pro（¥2,400/月）
- 4 人：GLM Max（¥1,600/月）
- 2 人：海外高阶（Cursor Pro+/Claude Code Teams 按需）
- 合计：约 ¥4,000-6,000/月

#### 100 人公司（多业务线）

- 80 人：GLM Pro
- 15 人：Qoder Teams 或 GLM Max（根据是否需要审计/团队治理）
- 5 人：海外增强座席（Cursor Business/Claude Teams）
- 合计：根据审计诉求与海外座席数量决定，建议先做试点测算再采购。

---

## 6. 落地路线图（公司多团队循序渐进）

> 落地不是“一天开通全员账号”，而是建立 **规范 + 试点 + 复制 + 治理** 的闭环。

### 6.1 建议里程碑（12 周模板，可按公司节奏调整）

| 周期        | 目标       | 关键交付                                           | 通过标准（能不能进下一阶段）       |
| ----------- | ---------- | -------------------------------------------------- | ---------------------------------- |
| 第 1-2 周   | 准备与对齐 | 使用规范、代理方案、仓库分级、预算与告警、试点名单 | 代理可用 + 合规确认 + 预算可控     |
| 第 3-6 周   | 试点落地   | 试点团队跑通补全/对话/审查 SOP；建立指标看板       | 指标不比基线差，且成本可解释       |
| 第 7-10 周  | 复制扩展   | 同业务线 3-5 个团队复制模板、固化仓库接入规范      | 运营体系可规模化（账号/配额/培训） |
| 第 11-12 周 | 公司级治理 | 座席分层、审计流程、离职回收、季度复盘机制         | 有回滚预案 + 能输出管理报告        |

### 6.2 角色与 RACI（建议落地前先定责）

| 事项           | 研发负责人 | 平台/中台 | 安全合规 | 采购财务 | 业务团队 TL |
| -------------- | ---------- | --------- | -------- | -------- | ----------- |
| 方案选型与原则 | A          | C         | C        | C        | C           |
| 代理/网络方案  | C          | A/R       | C        | -        | C           |
| 仓库分级与红线 | C          | R         | A/R      | -        | C           |
| 账号/SSO/回收  | C          | A/R       | C        | -        | C           |
| 预算/账单/告警 | A          | R         | C        | A/R      | C           |
| 培训与推广     | C          | R         | C        | -        | A/R         |
| 试点验收       | A          | R         | C        | C        | A/R         |

说明：A=最终负责，R=执行负责，C=协作/咨询。看不懂 RACI 也没关系：关键是每一项都有明确“拍板的人”和“干活的人”。

### 6.3 试点怎么做，结果才“说得清”

很多试点翻车不是“工具不行”，而是两件事没做好：**口径不统一**、**过程不可复用**。下面这套做法的目标很简单：试点结束后，你能用数据和案例回答清楚——“值不值、为什么值、下一步怎么扩”。

**(1) 先写清楚：通过/不通过的条件（避免试点结束才开始争论）**

- 选 4 类指标（见阶段 1）：产能、质量、体验、成本；每类至少 1 个“硬指标”。
- 写清楚“最低可接受标准”，例如：
  - 质量不下降：CI 失败率、线上缺陷率不高于基线（或有明确可解释原因）。
  - 成本可控：人均月成本不超过预算上限；触顶/故障重试可被降级策略吸收。
  - 体验可用：95 分位延迟与失败率在可接受区间（由平台/IT 提供数据）。

**(2) 用一套“真实任务样本”对比（避免“挑题做”）**

建议准备 10-20 个“真实任务样本”，覆盖 8.2 的高 ROI 场景，并记录最少信息：

| 字段        | 说明                                           |
| ----------- | ---------------------------------------------- |
| 任务类型    | 补全/小 bug/跨文件重构/补单测/PR Review/文档   |
| 仓库等级    | S0/S1/S2（决定允许能力与工具）                 |
| 复杂度      | 低/中/高（或 Story Points）                    |
| 基线耗时    | 试点前同类任务平均耗时（2-4 周窗口）           |
| AI 辅助耗时 | 试点期间耗时（含验证时间）                     |
| 验证方式    | 跑了哪些命令/截图/日志                         |
| 成本与失败  | 是否发生重试/超额/代理故障（以及怎么降级处理） |

**(3) 先把常见“试点错觉”写进复盘（避免“看起来提升”）**

- **人选偏差**：只让最强/最爱尝鲜的人用 → 尽量选“正常团队”，或分批灰度做对照。
- **新鲜感效应**：前 1-2 周提升很大、后面回落 → 试点至少 2-4 周，并单独看第 3-4 周的表现。
- **指标选错**：只看提交数会鼓励碎片化 → 同时看交付周期、返工率、缺陷率等质量指标。
- **外部干扰**：大版本/大促/人手变动会影响指标 → 记录关键事件，必要时只对同类任务做对比。

**(4) 试点结束必须产出的 3 件东西（否则很难复制）**

- “一页结论”：是否通过、通过条件是否满足、主要收益与代价、是否建议扩展。
- “可复制资产”：仓库接入模板（7.2）、日常 SOP（8）、培训材料、故障降级预案（9.1.5）。
- “治理数据”：账单样例、触顶次数、降级次数、代理故障次数、抽样审计结果。

### 阶段 0：基础准备（1-2 周）

**输出物（交付件）**

- 《AI 编程使用规范》（Do/Don’t、允许的仓库/文件类型、敏感信息处理）。
- 《网络与代理配置手册》（IDE/CLI 统一代理、故障排查）。
- 《座席分层与预算》（谁能用什么、如何申请升级、超额如何处理）。
- 《审计与留痕要求》（日志保存、审批流、回滚机制）。

**关键动作**

- 网络：确定海外代理出口、白名单域名、稳定性指标（例如 95 分位延迟 < 300ms）。
- 合规：建立“仓库分级”（涉密/一般/开源），明确每级允许的模型与功能（仅补全/允许 Agent/禁止上传）。
- 采购：海外信用卡/虚拟卡管控；国产发票与成本中心；设置预算上限与告警责任人。
- 工程：统一 PR 模板与仓库接入模板（`AI_RULES.md`/`.aiignore`/`.cursorignore`/`CLAUDE.md`），并要求所有新仓库默认带上。
- 指标：在试点前先采集 2-4 周基线（交付周期、PR 数、缺陷率、CI 失败率），否则试点“效果”无法客观评估。

### 阶段 1：试点（2-4 周，1-2 个低风险团队/仓库）

**选试点的原则**

- 优先选择：非涉密、迭代快、指标容易量化（例如 Web/工具链/中台项目）。
- 避免选择：强合规、强审计、外包多、依赖复杂且无法量化的项目作为第一个试点。

**试点最小可行配置（MVP）**

- 主力：GLM Pro 或 Qoder Pro（覆盖绝大多数人日常）
- 增强：1-2 个海外座席（Cursor Pro 或 Claude Code Pro），用于复杂任务对比
- 策略：默认国产/低价模型；高阶模型必须手动切换并记录原因（模板见后文）

**验收指标（建议至少选 4 个）**

- 产能：人均提交数/PR 数、交付周期、返工率（对比试点前 2-4 周基线）。
- 质量：PR 审查发现问题数、线上缺陷率、单测增量。
- 体验：补全采纳率、平均响应时间、失败率/重试率。
- 成本：人均月成本、超额次数、代理故障导致的重复调用次数。
- 对比口径：尽量按“同类任务 + 同时间窗口”对比，并记录版本发布/需求波峰等关键事件，避免把波动误判为收益或损失（见 6.3）。

**回滚预案**

- 一键禁用：插件/IDE 可快速关闭；路由切换到国产。
- 代理故障：提供备用节点/备用出口；明确故障期间“只允许补全，不允许 Agent”。

### 阶段 2：业务线扩展（4-8 周，同业务线复制）

**复制的关键不是“发账号”，而是“复制模板”**

- 复制：代理配置、索引黑名单、仓库接入模板、培训材料、指标看板。
- 分层路由：
  - 基线：国产（GLM/Qoder）+ 本地索引。
  - 提升：评审/复杂改造才切海外高质量模型（需要审批或留痕）。
  - 限额：按团队等级设月/周上限，触顶自动降级到国产/低价。

**推广培训**

- 10-15 分钟“快速上手”培训：快捷键、常用 Prompt、如何让 AI 写测试、如何审查 AI 输出。
- 30-45 分钟“进阶训练营”（核心成员）：跨文件重构、定位性能问题、生成迁移方案、拆分任务。

### 阶段 3：全公司规模化（持续）

**公司级治理要点**

- 账号与权限：SSO/成员管理；离职/转岗自动回收；关键岗位开更高档位。
- 指标与报表：月度用量、超额、延迟、故障次数、单位 PR 成本；对管理层输出 1 页报告。
- 规范固化：将“AI 生成代码必须跑测试/必须评审”的规则写进工程模板与 PR 模板。

### 阶段 4：优化与复盘（季度节奏）

- 成本优化：把高阶模型使用集中到“收益最大”的场景（评审、迁移、疑难）；日常用低价/国产。
- 体验优化：根据延迟与失败率，优化代理与路由策略；必要时切换主力供应商。
- 合规复核：更新敏感目录黑名单、出境白名单；抽样审计调用日志与 PR 记录。

---

## 7. “落地到每个项目”怎么做（仓库接入规范）

### 7.1 仓库分级（强烈建议公司统一）

| 等级         | 示例               | 允许的能力                                           | 建议工具                       |
| ------------ | ------------------ | ---------------------------------------------------- | ------------------------------ |
| S0（涉密）   | 核心算法、密钥仓库 | 禁止出境；允许本地索引；仅允许国产且禁止上传敏感文件 | GLM/Qoder（国产，本地索引）    |
| S1（内部）   | 大多数业务仓库     | 国产为主；海外白名单座席可用；必须审计               | GLM/Qoder + 少量 Cursor/Claude |
| S2（低风险） | 开源/公共/示例     | 可用海外；可更激进试验 Agent                         | Cursor/Claude/Codex/Gemini     |

### 7.2 每个仓库必须配置的“AI 约束文件”

> 目标：让 AI 有项目上下文，同时明确“哪些不能碰”。这些文件的最大价值在于“减少误用与泄漏”，并让新团队快速复制。

**建议统一放在仓库根目录：**

- `AI_RULES.md`：团队规则（允许/禁止上传目录、如何提问、审查要求）。
- `.aiignore`：敏感目录黑名单（`.env`、`secrets/`、`*.pem`、`id_rsa`、`*.p12`、`*.key` 等）。
- `docs/ai/`：放团队 Prompt 模板、示例、常见问题。

**如使用 Claude Code：**

- `CLAUDE.md`：声明项目结构、命令、测试入口、禁止触碰目录、代码风格。

**如使用 Cursor：**

- `.cursorignore`：同 `.aiignore`，并补充构建产物目录（`dist/`、`node_modules/`）。

#### 模板：`.aiignore`（建议公司统一并长期维护）

```gitignore
# Secrets / credentials
.env
.env.*
secrets/
**/secrets/
*.pem
*.key
*.p12
id_rsa
id_ed25519

# Customer / production data
data/
**/data/
*.sql
*.dump
*.bak
*.log

# Build outputs / noise
node_modules/
dist/
build/
coverage/
.turbo/
.next/
```

#### 模板：`AI_RULES.md`（每个仓库都应有）

```md
# AI 使用规则（本仓库）

## 允许
- 允许：补全、代码解释、小范围改动（限定目录）
- 允许：生成测试草稿（仅新增测试文件）
- 允许：生成文档草稿（需人工校对）

## 禁止
- 禁止上传/粘贴：任何密钥、证书、客户数据、未脱敏日志、数据库导出
- 禁止让 AI 修改：鉴权/支付/风控/数据出境相关代码（必须人工主导）
- 禁止在 S0 仓库使用海外模型

## 目录约束
- 允许改动目录：src/
- 禁止改动目录：secrets/、scripts/release/、infra/

## 验证要求
- 所有 AI 改动必须跑：pnpm test
- 有 UI 的必须提供：截图或录屏
```

#### 模板：`.cursorignore`（Cursor 仓库）

```gitignore
# Prefer reusing .aiignore content
.env
.env.*
secrets/
node_modules/
dist/
build/
coverage/
.turbo/
.next/
```

#### 模板：`CLAUDE.md`（Claude Code 仓库）

```md
# Project guidance for Claude Code

## Repo overview
- Tech stack: TypeScript (ESM), pnpm workspace
- Style: 2-space indent, keep changes minimal and focused

## Commands
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
- Format: pnpm format

## Do / Don't
- DO keep edits scoped; prefer small PRs
- DON'T touch secrets/, .env*, certificates, or customer data
- DON'T change release scripts unless explicitly asked

## Where to make changes
- Prefer editing: packages/**/src
- Tests live in: **/__tests__ or **/test
```

### 7.3 PR 模板必须加的两条（防止 AI 直上生产）

- “本 PR 是否使用 AI 生成/改写代码？若是，说明使用范围与已做的验证（测试/手工验证）。”
- “涉及安全/权限/支付/数据出境变更时，必须标记并请求安全复核。”

### 7.4 为每个项目沉淀 Skill（把 SOP 变成可复制资产）

> 这里的 Skill 指“可复用的提示词/工作流模板”（Codex CLI/内部 Agent 的本地 Skill），不是 Claude Code 的 npm Skill（见 [Skill（技能系统）](./basics/skill)）。

#### 7.4.1 为什么要做

- **把“怎么问 AI”产品化**：把高 ROI 的提问方式固化下来，新人照做就能用。
- **降低合规与误改风险**：把禁止目录、验收清单、默认命令写进 Skill，减少口头传达。
- **减少重复沟通成本**：同类项目的 SOP 复用，跨团队复制更快。

#### 7.4.2 每个项目的“最小 Skill 套件”（建议至少 5 个）

| Skill（示例命名）        | 解决什么                | 必填输入（写进 Skill）       | 输出/验收标准（写进 Skill）        |
| ------------------------ | ----------------------- | ---------------------------- | ---------------------------------- |
| `project-onboarding`     | 新人/新模型快速理解项目 | 项目结构、关键目录、风格规范 | 先复述约束；给出常用命令与入口     |
| `project-safe-change`    | 小改动不跑偏            | 允许/禁止目录、不可改行为    | 输出变更清单 + 风险点 + 验证命令   |
| `project-bug-triage`     | 定位 bug 与最小复现     | 如何跑本地、日志位置、开关   | 先给“复现步骤/假设列表/验证计划”   |
| `project-test-writer`    | 补测试草稿              | 测试框架、目录约定、运行命令 | 只新增测试文件；覆盖边界；能跑通   |
| `project-release-helper` | 发版/变更日志/版本策略  | 发版命令、分支策略、制品产出 | 产出 checklist；禁止直接改发布脚本 |

> 补充可选：前端项目加 `project-ui-regression`（截图/对照）、后端项目加 `project-api-contract`（接口变更与兼容）、工具链项目加 `project-ci-debug`（CI 失败定位）。

**Monorepo（pnpm workspace/Turbo 等）建议额外加 3 个**

- `monorepo-build-matrix`：把“每个 workspace 怎么 build/test/lint”的矩阵固化，避免只跑了错误的命令。
- `monorepo-deps-guard`：依赖升级/新增依赖的规则（workspace 协议、版本范围、锁文件策略、回滚方式）。
- `monorepo-release-flow`：发版与包发布的分步流程（变更集/版本号/制品校验/回滚点）。

**按项目类型，常见“加餐 Skill”**

| 项目类型                        | 建议新增 Skill             | 关注点（写进 Skill 的约束/验收）                         |
| ------------------------------- | -------------------------- | -------------------------------------------------------- |
| UI/小程序/前端应用              | `project-ui-regression`    | 必须给截图/录屏；必须跑构建；避免一次性大改 UI           |
| 核心库/工具包（packages）       | `project-api-compat-guard` | 不破坏公共 API；必须补单测；必要时更新变更日志/Changeset |
| 性能敏感模块                    | `project-perf-check`       | 需要基准对比；避免引入 O(n²)；给出性能验证方式           |
| e2e/快照密集项目                | `project-snapshot-guard`   | 明确何时允许更新快照；更新必须附原因与验证命令           |
| 文档站/示例工程（website/demo） | `project-docs-sync`        | 代码片段要可运行；链接不失效；示例与包版本同步           |
| CI/脚本/发布链路                | `project-ci-debug`         | 只做最小改动；先复现再修；必须提供回滚点与验证日志       |

**企业级 Skill 库建议分 3 层（避免“每个项目各写一份”）**

- **公司基线（Company Baseline）**：合规红线、验收清单、默认输出格式、PR 声明模板。
- **技术栈预设（Stack Presets）**：Node/Java/Go/小程序等常用命令与目录约定（测试/构建/格式化）。
- **项目覆盖（Project Overrides）**：只写这个项目独有的入口、特殊目录、特殊回滚策略。

#### 7.4.3 Skill 规格模板（统一输入/输出，便于复制与审计）

为避免 Skill 退化成“散落的提示词”，建议所有项目 Skill 统一用同一份规格模板（内容可精简，但字段要齐）：

```md
# Skill: <skill-name>

## Purpose（目的/适用场景）
- 解决什么问题？适用哪些任务？不适用哪些任务？

## Guardrails（红线与边界）
- 禁止目录/文件类型：
- 禁止行为（例如：改鉴权/支付/数据出境；改发布脚本）：
- 允许改动目录：
- 是否允许新增依赖？（默认不允许）

## Commands（项目命令）
- Install:
- Build:
- Test:
- Lint/Format:

## Output Format（输出格式要求）
- 变更点列表（文件级）
- 风险点与兼容性说明
- 验证命令与预期结果
- 回退策略（如何撤销/如何拆小 PR）

## Acceptance Criteria（验收标准）
- 必须通过哪些检查/测试？
- 是否需要截图/日志/性能对比？
- 是否需要更新文档/变更日志/Changeset？
```

#### 7.4.4 治理建议（避免 Skill 变成“散落的提示词”）

- **归属**：公司级通用 Skill 由平台/中台维护；项目 Skill 由项目 TL 维护（但必须走 code review）。
- **存放**：建议用独立仓库集中管理（便于版本化与审计），并按“项目/技术栈”分组。
- **变更管理**：Skill 的更新要附带“验证任务/验证命令”；重大变更先在试点团队灰度。

---

## 8. 日常使用 SOP（把 AI 变成标准流程）

### 8.1 默认路由策略（最重要的一条）

- **默认**：国产/低价模型（用于补全、小改动、查错、写注释、生成测试草稿）。
- **升级条件**：跨文件重构、架构迁移、复杂 bug、性能问题、核心模块 PR 审查 → 申请或切换到高阶模型。
- **禁止条件**：涉密仓库、密钥/证书/个人信息文件、未脱敏的生产日志、客户数据。

#### 8.1.1 任务分级与“用什么档位”（减少争论、降低成本）

| 任务类型                 | 推荐默认                | 何时升级到高阶/海外         | 验收要点               |
| ------------------------ | ----------------------- | --------------------------- | ---------------------- |
| Tab 补全/重命名          | 国产/低价               | 一般不需要                  | lint/类型检查通过      |
| 小范围修 bug（1-2 文件） | 国产/低价               | 需要跨模块定位/复杂并发问题 | 有最小复现 + 单测覆盖  |
| 重构（跨 3+ 文件）       | 国产（核心席位可高阶）  | 影响公共 API/核心模块       | 拆小 PR + 每步测试     |
| 单测补齐                 | 国产/低价               | 复杂边界/并发/时序          | 断言合理 + 覆盖边界    |
| PR Review                | 国产/低价（或工具自带） | 核心模块/安全模块           | 只做建议，人工裁决     |
| 文档/变更日志            | 国产/低价               | 对外发布、合规文本          | 人工校对、避免事实错误 |

#### 8.1.2 AI 输出的“最小验收清单”（团队统一口径）

- 改动范围是否符合约束（目录/文件/接口）？
- 是否引入新依赖或新权限？如果有，是否经过评审？
- 是否提供了可复现的验证方式（命令/截图/日志）？
- 是否通过：类型检查、lint、单测（至少跑到与改动相关的部分）？
- 是否新增/更新了测试覆盖关键分支？
- 是否存在“看似合理但业务语义错误”的风险点（尤其是边界条件）？

### 8.2 六类高 ROI 场景（建议先打穿）

1. **补全与重命名**：提高编码速度，成本低。
2. **代码解释与定位 bug**：让 AI 先给可能原因 + 最小复现路径，再人工确认。
3. **重构与抽象**：先让 AI 提方案（分步、小 PR），再逐步执行。
4. **单测生成**：只生成草稿；必须人工校对断言与边界；必须跑测试。
5. **PR 审查**：AI 先扫出明显问题（命名、空指针、边界、性能），人工做最终裁决。
6. **文档与变更日志**：自动生成草稿，发布前人工校对。

### 8.3 三个必须养成的习惯（否则越用越乱）

- **先约束再生成**：在提问里写清楚“不得修改哪些文件/目录、必须保留哪些行为”。
- **先小步再合并**：要求 AI “拆成 3-5 个小 PR”，每一步都可回滚、可测试。
- **先验证再相信**：AI 输出必须通过单测/类型检查/静态检查；不通过就当作建议而不是结果。

一个最简单的写法是：**目标 + 约束 + 验收**，三段写完再让 AI 开始干活。

示例（小改动）：

- 不推荐：帮我修一下这个 bug。
- 推荐：

```text
目标：修复 xxx 问题（不改变现有行为）。
约束：不改公共 API；不新增依赖；只允许改 src/xxx；不要修改 security/ 与 scripts/。
验收：给出改动点列表 + 风险点；并提供我应该运行的验证命令（pnpm test / pnpm lint）。
```

### 8.4 标准 Prompt 模板（可复制给团队）

下面 3 个模板可以直接复制，按需替换里面的占位符即可。

**模板 A：小改动（低价/国产）**

```text
目标：在不改变行为的前提下，完成【重命名/整理/修复 lint/修复小 bug】。
上下文：仓库是 <repo-name>，相关代码主要在 <path>。

约束：
- 不改公共接口（除非我明确允许）
- 不新增依赖
- 只允许改动：<allowed-paths>
- 禁止改动：<blocked-paths>

输出要求：
1) 改动点列表（按文件）
2) 风险点（可能影响的行为/边界）
3) 我应该运行的验证命令（例如 pnpm test / pnpm lint），以及预期看到什么
```

**模板 B：跨文件重构（高阶/核心座席）**

```text
目标：做一次跨文件重构/抽象（影响范围较大），但要可审查、可回滚。

约束：
- 把改动拆成 3-5 步（每步都能独立合并）
- 不要修改快照/锁文件（除非我明确允许）
- 禁止触碰 security/、scripts/release/ 等高风险目录
- 必须保持向后兼容（或明确写出破坏点并给迁移方案）

输出要求：
1) 先给分步计划：每步改哪些文件、为什么这么拆
2) 每步的验收：要跑哪些测试/命令、预期结果
3) 风险点：哪一步最容易出错、怎么回滚
```

**模板 C：单测生成**

```text
目标：为 <function/module> 补齐关键路径的单元测试/集成测试。

约束：
- 只允许新增测试文件（不要改业务逻辑）
- 覆盖边界：null/undefined、空数组/空字符串、异常分支、权限/鉴权（如有）
- 如果你需要 mock，请说明 mock 的理由与范围（避免过度 mock）

输出要求：
1) 测试用例清单（用一句话说明每个 case 覆盖什么）
2) 关键断言的理由（为什么这样断言）
3) 我应该运行的测试命令，以及预期看到什么
```

---

## 9. 网络、账号、合规（公司落地必须过的三关）

### 9.1 海外模型的网络打通（必做）

**核心原则：同一套代理策略覆盖 IDE + CLI + 浏览器登录。**
常见失败模式是：浏览器能登录、IDE 插件不能用、CLI 走直连被阻断，导致开发者反复重试、延迟暴涨、成本放大。

#### 9.1.1 代理部署建议（企业做法）

- 小规模（<20 人）：可先用单一出口，但必须有备用节点与切换文档。
- 中大规模（20+ 人）：建议由平台/IT 提供“统一代理服务”，至少具备：
  - 节点健康检查与自动切换
  - 按用户/团队限速（防止单人把带宽打满）
  - 访问日志（用于排障与合规审计，注意脱敏）

#### 9.1.2 CLI 代理环境变量（必须统一）

macOS/Linux（`~/.zshrc` / `~/.bashrc`）示例：

```bash
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"

# 内网域名与本机地址不要走代理（按公司实际补充）
export NO_PROXY="localhost,127.0.0.1,.corp.internal,10.0.0.0/8,192.168.0.0/16"
```

Windows PowerShell 示例：

```powershell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,.corp.internal"
```

#### 9.1.3 需要放行/可达的常见域名（按所选产品取舍）

- Cursor：`cursor.com`、`*.cursor.com`
- Claude/Anthropic：`claude.ai`、`claude.com`、`*.anthropic.com`
- OpenAI/ChatGPT：`openai.com`、`chatgpt.com`（部分地区可能 Cloudflare 风控更严）
- Google：`cloud.google.com`、`*.googleapis.com`、`*.gstatic.com`

建议做法：平台侧维护“域名白名单”，并在网络策略变更时同步更新。

#### 9.1.4 健康检查与排障（让开发者可自助）

- DNS：确认域名能解析（公司内网 DNS 不要劫持这些域名）。
- TLS：代理如果做了证书替换，需要明确安装企业根证书的流程（否则 IDE/CLI 会报证书错误）。
- 连通性：用 `curl -I https://cursor.com/pricing` 这类轻量请求做探测。
- 体验指标：至少记录“平均延迟/95 分位延迟/失败率”，并能定位到是“网络问题”还是“供应商限流”。

快速自检（给开发者的 1 分钟版本）：

```bash
# 1) DNS 能解析吗？
nslookup cursor.com

# 2) 走代理能连上吗？（看 HTTP 状态码即可）
curl -I https://cursor.com/pricing

# 3) 如果 CLI 总失败，先检查环境变量有没有被覆盖
env | grep -E 'HTTP_PROXY|HTTPS_PROXY|ALL_PROXY|NO_PROXY'
```

#### 9.1.5 故障时降级策略（必须写清楚）

- 代理异常：切换备用出口；在切换完成前仅允许补全，不允许 Agent 执行命令。
- 海外额度耗尽：降级到国产或低价模型，并冻结高阶座席的使用（避免“越急越烧钱”）。
- 供应商不可用：切换到另一家可用的方案（例如从 Cursor 临时切回 GLM/Qoder）。

### 9.2 账号与权限治理（避免“离职不回收”）

#### 9.2.1 基本要求（能做就不要“人工管理账号”）

- **优先团队/企业版**：至少要有成员管理与统一账单；最好有 SSO/审计日志。
- **禁止共享账号**：共享账号无法审计，也无法在离职时回收风险。
- **MFA**：要求开发者开启 MFA（尤其是拥有高阶座席/管理权限的人）。

#### 9.2.2 权限分层与申请流程（把“谁能用高阶”制度化）

- L1 普通开发：默认基础档位（国产 Pro / Cursor Pro）。
- L2 核心开发：按项目负责人提名或按指标（比如核心模块 ownership）授权。
- L3 审查/架构：拥有跨仓库权限，但必须接受更严格的审计与使用规范。
- 申请升级必须包含：仓库名称、使用场景、预计周期、验证方式、预算来源。

#### 9.2.3 离职/转岗回收（必须自动化）

- 与 IT/HR Offboarding 流程绑定：账号停用、座席回收、API/插件 token 失效（如存在）。
- 每月一次抽查：随机抽取 5-10 个账号核对在职状态与权限是否过大。

### 9.3 合规红线（建议写进制度）

#### 9.3.1 明确“什么算敏感”（给可执行的定义）

- 凭据类：密钥、证书、token、私钥、公钥、CI 密钥、签名文件。
- 数据类：客户数据、订单/支付信息、个人信息、生产数据库导出、未脱敏日志。
- 安全类：漏洞细节、攻防脚本、内部安全策略、未公开的架构与域名资产。

#### 9.3.2 红线策略（建议写成强制规则）

- **禁止上传**：以上敏感内容一律禁止粘贴/上传到任何外部模型。
- **涉密仓库禁出境**：S0 仓库默认禁止海外模型；如确需使用，必须先脱敏并走审批。
- **高风险模块双人复核**：鉴权/支付/风控/数据出境相关改动，AI 只能“建议”，最终必须双人 code review。
- **日志留痕**：至少保留“谁在什么仓库使用了什么能力”的记录；日志本身要脱敏且控制访问权限。

---

## 10. 方案落地要点（按产品拆解：怎么用到项目里）

> 这里强调“落地动作”，而不是产品宣传。每个方案都按：管理员准备 → 成员使用 → 仓库接入 → 治理与常见坑 来写。

### 10.1 Cursor（海外，体验优先，适合统一 IDE）

**适用**

- 希望统一 IDE/工作台，并把“补全 + Agent”作为主工作流。
- 海外网络、账号与采购链路已闭环，且能提供稳定代理与故障降级。

**不适用**

- 无法提供稳定海外网络（延迟高/失败率高）或无法在组织层面治理账号与账单。
- 团队强烈不愿切换 IDE（迁移成本高于收益）。

#### 管理员准备（公司/团队层）

1. 确认代理与白名单域名已就绪（见 9.1）。
2. 选择座席策略：
   - 普通开发：`Pro`
   - 核心开发/架构：`Pro+`（少量）
   - 需要 SSO/审计：`Business`
   - 极重度专项：`Ultra`（极少量）
3. 如果上 `Business`：优先完成 SSO 与成员回收流程，避免“账号散落”。
4. 设定团队规范：哪些仓库允许开 Agent、哪些仓库只允许补全。

#### 成员上手（个人层）

1. 安装 Cursor。
2. 在系统层配置代理，确保 Cursor、浏览器登录、终端一致走代理。
3. 先把日常习惯固化：
   - 80% 用 Tab 补全 + 小改动
   - 20% 才用 Agent 做跨文件重构/排障
4. 遇到“答非所问”，优先补充约束：不改行为、不改公共接口、必须通过测试。

#### 仓库接入（项目层）

- 必备：`AI_RULES.md` + `.cursorignore`（参考 7.2 模板）。
- 推荐：在 `AI_RULES.md` 写清楚“本仓库验证命令”（例如 `pnpm test`、`pnpm lint`）。
- 大仓库建议：先在子目录（模块）试点索引，不要一次性喂全仓库。

#### 治理与常见坑

- 坑 1：代理抖动导致 Agent 反复失败重试 → 成本增加。解决：故障时降级为“只补全”。
- 坑 2：没有忽略规则，索引了产物目录 → 回答质量下降、耗时变长。解决：维护 `.cursorignore`。
- 坑 3：重构一次性改太多 → PR 无法审查。解决：强制要求拆小 PR。

### 10.2 Claude Code（海外，CLI/Agent 强，适合重构与排障）

**适用**

- 团队更偏 CLI 工作流，或需要更强的 Agent 执行能力（读写多文件、跑命令、分步迁移）。
- 已经有相对标准的工程命令与仓库规范（安装/构建/测试/格式化），适合写进 `CLAUDE.md` 固化。

**不适用**

- 项目命令与工程规范不稳定（今天能跑、明天跑不了），或无法在仓库层面明确“允许/禁止目录”。
- 对执行命令与写文件权限无法做组织级边界约束与审计。

#### 管理员准备（公司/团队层）

1. 统一 Node 版本（建议 Node >= 18）与 npm 代理策略（避免装不上 CLI）。
2. 以团队为单位开通座席（`Pro`/`Teams`），并明确哪些成员有权限在 S1/S2 仓库使用。
3. 建立 `CLAUDE.md` 模板库：不同技术栈（Node/Java/Go）各一份，复制到仓库即可用。

#### 成员上手（个人层）

1. 安装 CLI（示例）：`npm i -g @anthropic-ai/claude-code`。
2. 登录：按官方流程授权；注意不要用个人账号绑定公司付费座席。
3. 使用方式建议：
   - 先让 Claude “写计划”，再让它“按步骤执行”
   - 对每一步要求输出：改动点 + 风险点 + 验证命令

#### 仓库接入（项目层）

- 必备：`CLAUDE.md` + `AI_RULES.md` + `.aiignore`。
- `CLAUDE.md` 要明确：
  - 如何跑测试/构建/格式化
  - 允许改动目录与禁止目录
  - 代码风格与约束（例如 2 空格、ESM、禁新增依赖）

#### 治理与常见坑

- 坑 1：Agent 默认“能写文件能跑命令”，权限边界不清。解决：`CLAUDE.md` 写清楚允许范围。
- 坑 2：把“执行命令”当作最终答案。解决：命令输出必须进入 PR 说明与人工复核。
- 坑 3：复杂迁移不拆分。解决：要求先输出 3-5 步迁移计划，并逐步合并。

### 10.3 Codex / ChatGPT Team（海外，团队通用，偏“知识+草稿”）

**适用**

- 跨团队通用场景：代码解释、技术调研、设计草稿、评审检查点、测试用例清单等“产出草稿/清单”的任务。
- 希望用 Team/企业版统一成员与账单，并把“深度改代码”留在 IDE/CLI 工具里完成。

**不适用**

- 把它当作“自动落地改代码”的主工具（缺少仓库上下文与工程约束时，风险高且质量不可控）。

#### 管理员准备（公司/团队层）

1. 优先 Team：统一成员、权限、账单，避免个人报销与账号散落。
2. 输出团队 Prompt 规范：
   - 必须写约束（目录/接口/依赖/测试）
   - 必须写验收方式（测试命令/截图/日志）
3. 为“核心模块”建立更严格的规则：AI 只能提供建议，不直接落地改动。

#### 成员上手（个人层）

- 典型用法：
  - 解释陌生代码、做技术调研、写设计草稿
  - 生成 PR Review 检查点列表
  - 生成测试用例清单（不是直接改业务代码）

#### 仓库接入（项目层）

- 依然需要仓库侧规则：`AI_RULES.md` + `.aiignore`。
- 核心模块 PR 要求：AI 输出必须包含“验证命令”，并在 PR 描述中说明已执行。

#### 治理与常见坑

- 坑 1：缺少仓库上下文导致“看起来对、实际错”。解决：让模型先复述项目约束与现有实现。
- 坑 2：生成大量代码但无测试。解决：把“必须补测试草稿”写进 SOP。

### 10.4 Gemini Coding Plan（海外，偏 PR Review 与 GCP 生态）

**适用**

- PR Review 辅助与质量扫描是核心诉求，且团队本身在 GCP 生态中工作较多。
- 账号与账单体系可以纳入公司治理（而不是个人零散账号）。

**不适用**

- 团队没有稳定的 Google 账号与账单体系，或无法满足组织级成员管理与审计要求。

#### 管理员准备（公司/团队层）

1. 确认 Google 账号与 GCP 账单体系可用（否则推进会卡住）。
2. 明确 PR Review 权责：AI 是辅助审查，最终由代码所有者裁决并承担责任。
3. 选择座席：Standard 覆盖多数人；Enterprise 给审查角色或核心项目。

#### 成员上手（个人层）

- 建议把 Gemini 用在两类任务：
  - PR Review：提示潜在 bug、边界条件、性能问题
  - 与 GCP 相关的代码/配置：更容易给出生态内建议

#### 仓库接入（项目层）

- PR 模板明确：AI Review 只是建议，必须人工确认与验证。
- 对大型 PR：限制 diff 大小、先拆 PR 再用 AI 审查。

### 10.5 GLM（国产主力，适合全员普及）

**适用**

- 合规与报销友好，希望快速全员覆盖，把补全/小改动/补测先规模化落地。
- 希望把“默认路由”稳定在国产/低价侧，通过座席分层控制成本波动。

**不适用**

- 强依赖海外生态（账号/插件/模型）且无法接受国产作为默认兜底的组织（这类通常要先解决 Gate 条件）。

#### 管理员准备（公司/团队层）

1. 以 GLM Pro 作为默认座席（覆盖 70-85% 人群），Max 作为核心席位。
2. 把“5 小时刷新”写进团队排班：批量重构/补测任务集中在刷新后执行。
3. 建立用量看板：每日/每周触顶风险提示（尤其是 Max 席位）。

#### 成员上手（个人层）

- 优先打穿三件事：
  1. Tab 补全
  2. 小范围修 bug（要求先给复现与验证命令）
  3. 单测草稿（要求覆盖边界与异常）

#### 仓库接入（项目层）

- 必备：`AI_RULES.md` + `.aiignore`。
- S0 仓库：只允许国产，并强制启用敏感目录黑名单。

#### 治理与常见坑

- 坑 1：刷新周期误解导致“额度突然用完”。解决：把批量任务集中到刷新后窗口。
- 坑 2：把 AI 当成“自动提交器”。解决：统一验收清单（8.1.2）与 PR 模板。

### 10.6 Qoder（国产/混合，治理友好）

**适用**

- 既要国产可用性/合规友好，又希望在少数仓库/少数人上引入海外增强，并要求审计与团队治理。
- 希望把“混合路由”做成可控的白名单能力（默认关、按需开、可追溯）。

**不适用**

- 混合路由无法在组织层面做审批与审计（否则风险会集中爆发在“默认开”上）。

#### 管理员准备（公司/团队层）

1. 普通席位 `Pro`，重度/混合需求 `Pro+`，需要审计与成员管理用 `Teams`。
2. 建立混合路由白名单：哪些仓库/分支允许海外模型，谁可以开。
3. 配额策略：团队配额 + 个人上限，触顶自动降级到国产模型。

#### 成员上手（个人层）

- 建议默认国产路由，只有在“确实需要高质量推理/迁移方案”时才申请混合。
- 大改动先输出分步计划，再开始改代码。

#### 仓库接入（项目层）

- 必备：`AI_RULES.md` + `.aiignore`；团队版建议开启审计与操作留痕。
- 对涉密仓库：强制关闭海外路由。

#### 治理与常见坑

- 坑 1：混合路由“默认开”会直接引入合规风险。解决：默认关、审批开。
- 坑 2：缺少审计导致问题难追溯。解决：团队版启用审计并定期抽查。

---

## 11. 执行清单（公司落地逐项勾）

### 11.1 决策与采购

- [ ] 完成 Gate A/B：合规出境范围书面结论 + 海外网络与采购闭环确认。
- [ ] 明确默认主力（国产/海外）与增强座席策略。
- [ ] 选定座席分层与数量（L1/L2/L3/L4）。
- [ ] 账单中心与预算上限、告警责任人。
- [ ] 供应商可用性评估（区域、风控、支付）。
- [ ] 输出选型评审交付物（见 2.4）：主力+降级、约束条件、落地计划、风险与回滚。

### 11.2 网络与合规

- [ ] 海外代理可用（IDE/CLI 同策略），有备用出口。
- [ ] 代理健康检查与故障降级策略可执行（见 9.1.4/9.1.5）。
- [ ] 仓库分级（S0/S1/S2）完成，并绑定策略。
- [ ] 敏感目录黑名单（`.env`/`secrets/`/证书/客户数据）固化到模板。
- [ ] 审计与留痕（谁用、用在哪个仓库、做了什么）可追溯。

### 11.3 项目接入

- [ ] 每个仓库落地 `AI_RULES.md` / `.aiignore` /（可选）`CLAUDE.md` / `.cursorignore`。
- [ ] 关键工作流沉淀为项目 Skill（见 7.4），并用 1-2 个真实任务验证可用。
- [ ] PR 模板增加 AI 使用声明与验证说明。
- [ ] 将“必须跑测试/必须 code review”固化到工程规范。

### 11.4 运营与复盘

- [ ] 试点指标看板（效率/质量/体验/成本）建立。
- [ ] 试点“一页结论”与可复制资产沉淀（见 6.3）：模板、SOP、培训、降级预案、账单样例。
- [ ] 月度复盘机制：座席调整、路由调整、代理优化、合规抽查。
- [ ] 回滚预案演练（代理故障/额度耗尽/供应商不可用）。

---

## AI 编码助手五大方案选型指南

# AI 编程五大方案选型指南

## 概述

本文档将深入对比当前最主流的五种 AI 编程方案：**AWS Kiro**、**GitHub Copilot**、**Cursor IDE**、**Claude Code** 和 **OpenAI Codex**，帮助开发者根据自身需求选择最适合的工具。

| 方案             | 国内可用性 | 网络要求            |
| ---------------- | ---------- | ------------------- |
| **AWS Kiro**     | ✅ 可直接用 | 无需代理            |
| **GitHub Copilot** | ✅ 可直接用 | 无需代理            |
| **Cursor IDE**   | ❌          | 需要美国节点/代理   |
| **Claude Code**  | ❌          | 需要美国节点/代理   |
| **OpenAI Codex** | ❌          | 需要美国节点/代理   |

---

## 国内直接可用方案

> **说明**：以下方案在中国大陆地区可直接访问，无需复杂的网络配置。

### 方案一：AWS Kiro ✅ 国内直接可用

### 选择理由

**Kiro** 是 Amazon AWS 推出的 AI 原生 IDE，采用独特的 Spec-Driven（规格驱动）开发模式：

- **国内直接可用**：通过 AWS 中国区域提供服务，**中国大陆用户无需代理即可访问**
- **AWS 背景加持**：由 Amazon 官方支持，依托 AWS 基础设施，企业级可靠性
- **Spec-Driven 开发**：独特的"先计划后构建"模式，将需求转化为可执行的规格说明
- **Claude 4.5 全系列**：支持 **Claude Opus 4.5**、Sonnet 4.5、Haiku 4.5 全系列模型
- **智能模型选择**：Auto 模式可根据任务复杂度自动选择最合适的模型
- **VS Code 架构**：基于 VS Code fork，界面熟悉，上手容易
- **Agent Hooks**：支持自动化触发器，工作流可定制
- **新用户福利**：注册后第一个月赠送 500 积分用于体验

### ⚠️ 中国用户注意事项

> **重要提示**：虽然 Kiro 目前在中国可通过 AWS 中国区域访问，但需要注意：
>
> 1. **政策风险**：各类产品的迭代与政策可能随时变化，不能保证一直可以在国内使用
> 2. **Anthropic 限制**：Claude 官方已于 2025 年 9 月更新政策，禁止中国控制的实体使用 Claude 服务
> 3. **AWS Bedrock 渠道**：Kiro 通过 AWS Bedrock 提供 Claude 模型访问，目前 AWS 中国区域仍可正常使用
> 4. **变化无常**：如遇访问问题，建议关注 AWS 中国官方公告或考虑替代方案

### 个人订阅方案

| 套餐      | 月费    | Credits                           | 超量使用                 |
| --------- | ------- | --------------------------------- | ------------------------ |
| **试用**  | -       | 50 credits/月 + 首月赠送 500      | 不可超量，用完需等待下月 |
| **Pro**   | $20/月  | 1,000 credits/月                  | $0.04/credit             |
| **Pro+**  | $40/月  | 2,000-3,000 credits/月            | $0.04/credit             |
| **Power** | $200/月 | 10,000 credits/月                 | $0.04/credit             |

**使用说明**：

- **试用额度**：每月 50 credits，新用户第一个月额外赠送 500 credits
- **刷新周期**：每月按订阅日期重置
- **超额处理**：付费套餐（Pro/Pro+/Power）可超量使用，按 $0.04/credit 计费
- **升级保留**：30 天内升级可保留未使用的试用额度

### 团队订阅方案

| 套餐           | 价格     | 最低人数  | 核心功能                                                                  |
| -------------- | -------- | --------- | ------------------------------------------------------------------------- |
| **Enterprise** | 定制定价 | **20 人** | 所有个人功能 + SSO/SCIM + 集中许可证管理 + 组织策略 + AWS 集成 + 专属支持 |

### 技术特点

| 特性            | 说明                                                   |
| --------------- | ------------------------------------------------------ |
| **Spec-Driven** | 将想法转化为"活的可执行规格"，自动应用软件工程最佳实践 |
| **主要模型**    | **Claude Opus 4.5**、Sonnet 4.5、Haiku 4.5 |
| **架构基础**    | 基于 VS Code                                           |
| **扩展协议**    | 支持 MCP (Model Context Protocol)                      |

#### Claude 4.5 模型 Credit 倍率

| 模型             | Credit 倍率 | 适用场景                         |
| ---------------- | ----------- | -------------------------------- |
| **Haiku 4.5**    | 0.4×        | 快速、低成本任务                 |
| **Sonnet 4.5**   | 1.3×        | 复杂代理和编码（推荐大多数场景） |
| **Opus 4.5**     | 2.2×        | 最强推理能力，最具挑战性的任务   |

### 参考链接

- [Kiro 官方网站](https://kiro.dev/)
- [Kiro 官方定价页面](https://kiro.dev/pricing/)
- [AWS 中国 Kiro CDK 教程](https://aws.amazon.com/cn/blogs/china/blog-03-kiro-ai-cdk-development/)

---

### 方案二：GitHub Copilot ✅ 可直接用

### 选择理由

**GitHub Copilot** 是由 GitHub 和 OpenAI 联合开发的 AI 编程助手，是目前市场上最早的、用户基数最大的 AI 编码工具：

- **市场先驱**：2021年首次发布，用户数超过 150 万，占 AI 编程工具市场主导地位
- **深度集成**：与 GitHub 生态深度整合，支持 VS Code、Visual Studio、JetBrains 全系列 IDE
- **多模型支持**：支持 **Claude 4.5**（Sonnet/Opus/Haiku）、**GPT 5.2**、**Gemini Pro 3** 等多种模型
- **企业级支持**：GitHub 背书，企业版提供完善的权限管理和安全合规
- **Premium 请求系统**：2025年引入新的 premium requests 计费模式
- **⚠️ 国内限制**：中国大陆地区访问需要稳定的网络环境

### 个人订阅方案（2025-2026 最新）

| 套餐        | 月费       | 年费            | 核心额度                                                     |
| ----------- | ---------- | --------------- | ------------------------------------------------------------ |
| **Free**    | 免费       | 免费            | 基础代码补全，有限的 Copilot Chat 功能                       |
| **Pro**     | $10/月     | $100/年 (省17%) | 完整代码补全 + Copilot Chat + CLI + 多文件编辑               |
| **Pro+**    | $39/月     | -               | 全模型访问 + **1,500 次 premium 请求/月** + 超量 $0.04/次    |

**使用说明**：

- **Free 限制**：基础代码补全，有限的 Chat 功能
- **Pro 功能**：完整 Copilot 功能，包括代码补全、Chat、CLI
- **Pro+ 额度**：每月 1,500 次 premium 请求（使用更强大的模型）
- **超量计费**：Pro+ 超出部分按 **$0.04/次** 计费
- **刷新周期**：每月按订阅日期重置

### 支持的 AI 模型（2026）

| 模型分类       | 具体模型                              | 说明                     |
| -------------- | ------------------------------------- | ------------------------ |
| **OpenAI**     | **GPT 5.2**、o3、o4-mini              | OpenAI 最新推理模型     |
| **Anthropic**  | **Claude 4.5**（Sonnet/Opus/Haiku）   | Claude 最新高性能模型   |
| **Google**     | **Gemini Pro 3**                      | Google 最新推理模型      |

> **注意**：模型可用性会根据 GitHub 和各 AI 提供商的合作协议动态调整。部分高级模型需要 Pro+ 订阅。

### 团队订阅方案

| 套餐           | 价格          | 最低人数   | 核心功能                                                                      |
| -------------- | ------------- | ---------- | ----------------------------------------------------------------------------- |
| **Business**   | $19/人/月     | -          | Pro 功能 + 管理控制台 + 组织策略 + 数据不训练 + 使用统计                      |
| **Enterprise** | $39/人/月     | -          | Business 全部 + SSO 单点登录 + 审计日志 + 私有化部署 + 专属支持 + 合规认证    |

**Business/Enterprise 额外功能**：

- **管理控制台**：集中管理用户许可证和策略
- **单点登录 (SSO)**：支持 SAML 2.0 和 SCIM
- **数据隐私**：承诺不使用企业代码训练模型
- **使用统计**：详细的使用报告和分析
- **合规认证**：SOC 2、ISO 27001 等认证

### 技术特点

| 特性              | 说明                                                         |
| ----------------- | ------------------------------------------------------------ |
| **支持的 IDE**    | VS Code、Visual Studio、JetBrains 全系列、Vim/Neovim         |
| **Copilot Chat**  | 交互式对话编程，支持代码库级别的上下文理解                   |
| **Copilot CLI**   | 命令行工具，可直接在终端使用                                 |
| **Copilot Workspace** | AI 驱动的开发环境，支持从需求到代码的完整工作流          |

### 参考链接

- [GitHub Copilot 官方定价页面](https://github.com/features/copilot/plans)
- [GitHub Copilot 官方文档](https://docs.github.com/en/copilot/get-started/plans)
- [GitHub Copilot 支持的 AI 模型](https://docs.github.com/zh/copilot/reference/ai-models/supported-models)
- [GitHub Copilot 请求计费说明](https://docs.github.com/en/copilot/concepts/billing/copilot-requests)
- [GitHub Copilot Pricing Guide 2026](https://userjot.com/blog/github-copilot-pricing-guide-2025)

---

## 需要美国节点的方案

> **说明**：以下方案在中国大陆地区**无法直接访问**，需要美国节点或海外代理。

### 方案三：Cursor IDE ❌ 需要美国节点

### 选择理由

**Cursor** 是目前市场上最成熟的 AI 原生 IDE，基于 VS Code fork 而来，深度集成 AI 能力：

- **AI 原生体验**：专为 AI 编程设计，而非插件形式，体验更流畅
- **预测式补全**：可预测 5-10 行代码，补全质量业界领先
- **跨文件重构**：支持项目级别的代码理解和重构
- **Agent 模式**：Background Agent 可在后台自动完成复杂任务
- **生态完善**：v1.0/v1.1 新增 BugBot 审查、Memory 能力
- **市场地位**：估值 99 亿美元，年化收入 5 亿美元
- **⚠️ 国内限制**：中国大陆地区访问需要稳定的网络环境

### 个人订阅方案

| 套餐      | 月费 (月付) | 月费 (年付)     | 核心额度                                             |
| --------- | ----------- | --------------- | ---------------------------------------------------- |
| **Hobby** | 免费        | 免费            | 基础功能，有限 AI 模型访问                           |
| **Pro**   | $20/月      | ~$16/月 (省20%) | 约 500 次 fast premium requests/月，包含 $20 API额度 |
| **Pro+**  | $60/月      | -               | 3x 所有模型使用额度，包含 $70 API额度                |
| **Ultra** | $200/月     | -               | 20x 所有模型使用额度，包含 $400 API额度              |

**使用说明**：

- **Fast Requests**：Pro 计划每月约 500 次快速请求
- **Slow Requests**：超出后自动切换到慢速请求，无次数限制
- **刷新周期**：每月按订阅日期重置（如 15 日订阅则每月 15 日重置）
- **部分恢复**：用尽额度后 5-24 小时内可能会恢复少量额度

### 团队订阅方案

| 套餐           | 价格      | 核心功能                                                                     |
| -------------- | --------- | ---------------------------------------------------------------------------- |
| **Teams**      | $40/人/月 | 所有 Pro 功能 + SSO 单点登录 + 管理控制台 + 使用分析 + 组织级隐私模式 + RBAC |
| **Enterprise** | 定制定价  | Teams 全部功能 + SCIM 用户预配 + 数据不用于训练 + 专属支持 + 更多企业功能    |

**Teams 最低要求**：无明确最低人数要求

### 参考链接

- [Cursor 官方定价页面](https://cursor.com/pricing)
- [Cursor Teams 定价详情](https://cursor.com/docs/account/teams/pricing)
- [Cursor 企业版介绍](https://cursor.com/enterprise)

---

### 方案四：Claude Code ❌ 需要美国节点

### 选择理由

**Claude Code** 是 Anthropic 推出的 CLI 工具，可与现有开发环境无缝集成：

- **顶尖代码能力**：Claude Opus 4.5 在编程基准测试中表现卓越
- **CLI 工具**：不改变现有 IDE 习惯，通过命令行与 AI 交互
- **深度代码理解**：可处理大型代码库，支持跨文件重构和代码审查
- **MCP 协议支持**：可扩展连接各种工具和数据源
- **成本效益**：相对较低的价格获得高质量编程辅助
- **⚠️ 国内限制**：Anthropic 已禁止中国用户使用

### 个人订阅方案

| 套餐        | 月费 (月付) | 月费 (年付)       | 核心额度                                                   |
| ----------- | ----------- | ----------------- | ---------------------------------------------------------- |
| **Pro**     | $20/月      | $17/月 (年付$200) | 约 5x 免费用量，优先队列                                   |
| **Max 5x**  | $100/月     | -                 | 5x Pro 额度，预计 140-280 小时 Sonnet 4/周                 |
| **Max 20x** | $200/月     | -                 | 20x Pro 额度，约 900 条消息/5小时 或 200-800 prompts/5小时 |

**使用说明**：

- **刷新周期**：5 小时滚动窗口
- **周限额**：自 2024 年 8 月 28 日起引入周限额
- **超额处理**：达到限制后可选择升级或等待刷新

### 团队订阅方案

| 套餐                | 价格                                 | 最低人数 | 核心功能                                                    |
| ------------------- | ------------------------------------ | -------- | ----------------------------------------------------------- |
| **Team (Standard)** | $30/人/月 (月付)$25/人/月 (年付) | **5 人** | Sonnet/Opus 高额度 + 团队共享池 + 管理后台 + 成员管理 + SSO |
| **Team (Premium)**  | $150/人/月                           | 5 人     | Standard 全部 + Premium 优先队列 + 更高配额 + 审计日志      |
| **Enterprise**      | 联系销售                             | -        | 企业级功能 + DPA/BAA 合同 + 专属支持 + 定制部署             |

### 参考链接

- [Claude 官方定价页面](https://claude.com/pricing)
- [Claude Code 使用指南](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)

---

### 方案五：OpenAI Codex (ChatGPT) ❌ 需要美国节点

### 选择理由

**OpenAI Codex** 已整合到 ChatGPT 订阅中，提供业界领先的代码生成能力：

- **GPT 5.2 模型**：最新一代模型，代码生成能力业界领先
- **o3/o4-mini 推理模型**：专为复杂编程和推理优化
- **深度集成**：ChatGPT 网页版、CLI、API 全覆盖
- **Code Interpreter**：可执行代码进行数据分析
- **生态成熟**：插件系统最完善，第三方工具支持最广泛
- **多模态能力**：支持图像、音频等多种输入方式

> **注意**：原独立 Codex API 已整合到 GPT-5 模型家族中，不再单独提供

### 个人订阅方案

| 套餐     | 月费    | 核心额度                                                                                    |
| -------- | ------- | ------------------------------------------------------------------------------------------- |
| **Free** | 免费    | GPT 5.2: 约 10 条/5小时                                                                      |
| **Plus** | $20/月  | GPT 5.2: 160 条/3小时o3-mini: 150 条/天o3: 100 条/周o4-mini: 300 条/天             |
| **Pro**  | $200/月 | 声称"无限消息"+ GPT 5.2 Pro更快图像生成 + 最大深度研究额度实际仍可能遇到 5 小时限制 |

**使用说明**：

- **Free 刷新周期**：5 小时滚动窗口
- **Plus 刷新周期**：3 小时滚动窗口（GPT 5.2），部分模型按天/周计算
- **Pro 说明**：官方宣传"无限"，但用户报告仍可能遇到限制

### 团队订阅方案

| 套餐           | 价格                                 | 最低人数          | 核心功能                                      |
| -------------- | ------------------------------------ | ----------------- | --------------------------------------------- |
| **Team**       | $30/人/月 (月付)$25/人/月 (年付) | **2 人**          | GPT 5.2 访问 + 协作工具 + 团队管理 + 数据不训练 |
| **Business**   | $25-30/人/月                         | -                 | Team 全部 + 管理控制台 + SSO + 数据分析       |
| **Enterprise** | 联系销售                             | 通常 100-150 人起 | 企业级合规 + DPA/BAA + 私有端点 + 专属支持    |

**Team/Business 额外功能**：

- 管理控制台和用户管理
- 单点登录 (SSO)
- 数据不用于训练保证
- 团队协作空间
- 使用分析和报告

### API 定价（按量计费）

如需通过 API 使用 Codex 能力：

| 模型                   | 输入 Token        | 缓存输入           | 输出 Token         |
| ---------------------- | ----------------- | ------------------ | ------------------ |
| **GPT 5.2-mini**       | $0.25 / 1M tokens | $0.025 / 1M tokens | $1.00 / 1M tokens  |
| **GPT 5.2**            | $1.75 / 1M tokens | $0.175 / 1M tokens | $14.00 / 1M tokens |

**新用户福利**：新 API 账户可获得 $5 免费额度（约 400 万 GPT 5.2 tokens）

### 参考链接

- [ChatGPT 官方定价页面](https://chatgpt.com/pricing)
- [ChatGPT Pro 方案](https://chatgpt.com/plans/pro/)
- [OpenAI API 定价](https://openai.com/api/pricing/)
- [OpenAI 定价说明](https://platform.openai.com/docs/pricing)
- [ChatGPT 使用限制说明](https://northflank.com/blog/chatgpt-usage-limits-free-plus-enterprise)
- [OpenAI Codex 定价指南](https://userjot.com/blog/openai-codex-pricing)
- [GPT-5.2 定价说明](https://www.glbgpt.com/hub/chatgpt-5-2-price-guide-2025/)

---

## 五大方案对比总结

### 价格对比（个人版）

| 方案               | 入门价格                       | 中级价格          | 高级价格           | 刷新周期 |
| ------------------ | ------------------------------ | ----------------- | ------------------ | -------- |
| **AWS Kiro**       | 50 积分/月 + 首月赠送 500      | $20/月 (Pro)      | $200/月 (Power)    | 月度重置 |
| **GitHub Copilot** | $10/月 (Pro)     | $39/月 (Pro+)     | -                  | 月度重置 |
| **Cursor**         | $20/月 (Pro)     | $60/月 (Pro+)     | $200/月 (Ultra)    | 月度重置 |
| **Claude Code**    | $20/月 (Pro)     | $100/月 (Max 5x)  | $200/月 (Max 20x)  | 5小时/周 |
| **OpenAI Codex**   | $20/月 (Plus)    | -                 | $200/月 (Pro)      | 3-5小时  |

### 价格对比（团队版）

| 方案               | 团队价格       | 最低人数   | 企业版             |
| ------------------ | -------------- | ---------- | ------------------ |
| **AWS Kiro**       | -              | **20 人**  | 定制               |
| **GitHub Copilot** | $19/人/月      | -          | $39/人/月          |
| **Cursor**         | $40/人/月      | 无明确要求 | 定制               |
| **Claude**         | $25-30/人/月   | **5 人**   | 定制               |
| **OpenAI**         | $25-30/人/月   | **2 人**   | 定制 (通常100人起) |

### 刷新周期对比

| 方案               | 个人版刷新 | 团队版刷新 | 特点                     |
| ------------------ | ---------- | ---------- | ------------------------ |
| **AWS Kiro**       | 每月重置   | 每月重置   | 支持$0.04/credit超量计费 |
| **GitHub Copilot** | 每月重置   | 每月重置   | Pro+ 超量 $0.04/次       |
| **Cursor**         | 每月重置   | 每月重置   | 5-24小时可能部分恢复     |
| **Claude**         | 5小时/周   | 5小时/周   | 窗口期最短               |
| **OpenAI**         | 3-5小时    | 3-5小时    | Plus 3小时，Free 5小时   |

### 国内可用性对比

| 方案               | 国内直接访问 | 需要美国节点 | 说明                                  |
| ------------------ | ------------ | ------------ | ------------------------------------- |
| **AWS Kiro**       | ✅           | ❌            | 通过 AWS 中国区域可访问，但有政策风险 |
| **GitHub Copilot** | ✅           | ❌            | 可直接访问                             |
| **Cursor**         | ❌            | ✅           | 需要美国节点或代理                      |
| **Claude Code**    | ❌            | ✅           | 需要美国节点或代理                      |
| **OpenAI Codex**   | ❌            | ✅           | 需要美国节点或代理                      |

### 选型建议

**选择 AWS Kiro 如果**：

- **位于国内**，希望无需代理即可使用
- 偏好 Spec-Driven（规格驱动）开发模式
- 团队已使用 AWS 生态系统
- 需要企业级可靠性和数据合规
- 可以接受潜在的政策变化风险

**选择 GitHub Copilot 如果**：

- 已习惯使用 VS Code/JetBrains 等 IDE
- 需要最成熟稳定的 AI 编码工具
- 预算有限，$10-39/月的价格更有吸引力
- 团队已深度使用 GitHub 生态
- 需要企业级合规和支持

**选择 Cursor 如果**：

- 希望使用 AI 原生 IDE，不想折腾插件
- 需要预测式代码补全和跨文件重构
- 团队需要统一的 IDE 环境和管理
- 预算 $20-200/月可接受
- 有稳定的海外网络环境

**选择 Claude Code 如果**：

- 已习惯现有 IDE (VS Code/JetBrains)，不想切换
- 需要顶尖的代码理解和审查能力
- 希望通过 CLI 与 AI 交互
- 需要频繁处理大型代码库
- 有稳定的海外网络环境

**选择 OpenAI Codex 如果**：

- 需要 GPT-5.2/o3 等最新推理模型
- 需要多模态能力（图像、音频）
- 需要 Code Interpreter 进行数据分析
- 需要 API 接入自定义应用
- 有稳定的海外网络环境

---

## 附录：Anthropic 公司股东与融资信息

### 公司背景

**Anthropic** 是一家美国人工智能安全公司，由 Dario Amodei 和 Daniela Amodei 于 2021 年创立。公司前身为 OpenAI 的核心成员，后独立发展专注于 AI 安全研究。Anthropic 推出了 Claude 系列 AI 模型，包括 Haiku、Sonnet 和 Opus。

### 融资历程与估值

#### 最新融资（2026 年 1 月）

| 融资轮次 | 金额          | 估值          | 领投方        | 状态         |
| -------- | ------------- | ------------- | ------------- | ------------ |
| **Series G** | **$100 亿**  | **$3500 亿**  | **GIC**（新加坡主权财富基金） | 洽谈中       |

#### 历史主要融资

| 时间       | 轮次      | 金额         | 估值        | 主要投资方                           |
| ---------- | --------- | ------------ | ----------- | ------------------------------------ |
| 2025年9月  | Series F  | $130 亿      | $1830 亿    | Lightspeed、Fidelity 等              |
| 2024年     | 多轮      | 累计约 $170+亿 | -          | Google、Amazon、Spark Capital 等      |
| 2023年     | -         | $40 亿（Amazon投资） | -      | Amazon                               |
| 2023年     | -         | $20 亿（Google投资） | -      | Google                               |

**累计融资金额**：至少 **$400 亿**（约 14 轮融资）

### 主要股东与投资方

#### 机构投资者

| 投资方              | 类型                | 投资轮次/金额                    |
| ------------------- | ------------------- | -------------------------------- |
| **GIC**             | 新加坡主权财富基金   | 领投 Series G（洽谈中）           |
| **Lightspeed Venture Partners** | 风险投资       | Series F 领投                   |
| **Fidelity Management & Research** | 资产管理   | 多轮投资                        |
| **Google (Alphabet)** | 战略投资者         | $20 亿 + 多轮投资                |
| **Amazon**          | 战略投资者         | $40 亿投资，云服务合作           |
| **Spark Capital**   | 风险投资           | 早期及后续轮次                   |
| **Menlo Ventures**  | 风险投资           | 早期投资者                      |

#### 战略合作

- **Amazon AWS**：Anthropic 选择 AWS 作为主要云服务提供商，Amazon 累计投资 $40 亿
- **Google Cloud**：Google 投资并提供云基础设施支持

### 财务预期

| 指标            | 数据                          |
| --------------- | ----------------------------- |
| **2025 年 ARR 预期** | $90 亿                        |
| **2026 年收入预期** | $200-260 亿                   |
| **增长率**       | 3 年期内约 13-28% 增长预期    |

### 上市计划

根据多家媒体报道：
- **IPO 时间窗口**：最早可能在 **2026 年底** 或 2027 年
- **上市地点**：预计在美国公开市场上市
- **当前状态**：已开始筹备上市相关工作

### 参考链接

- [Anthropic 寻求 100 亿美元融资，估值达 3500 亿美元 - The New York Times](https://www.nytimes.com/2026/01/07/technology/anthropic-funding-valuation.html)
- [Anthropic 以 3500 亿美元估值筹集 100 亿美元 - Wall Street Journal](https://www.wsj.com/tech/ai/anthropic-raising-10-billion-at-350-billion-value-62af49f4)
- [Anthropic 瞄准 3500 亿美元估值进行大规模融资 - Yahoo Finance](https://finance.yahoo.com/news/anthropic-eyes-350-billion-valuation-190120429.html)
- [Anthropic 计划以 3500 亿美元估值筹集 100 亿美元 - Seeking Alpha](https://seekingalpha.com/news/4537469-anthropic-plans-to-raise-10b-at-350b-valuation)
- [Anthropic 寻求 100 亿美元融资，估值 3500 亿美元 - SiliconANGLE](https://siliconangle.com/2026/01/07/anthropic-reportedly-seeking-raise-10b-350-billion-valuation/)
- [Anthropic 公司介绍 - Wikipedia](https://en.wikipedia.org/wiki/Anthropic)
- [Anthropic 股权投资指南 - TSG Invest](https://tsginvest.com/anthropic-pbc/)

---

> **最后更新时间**：2026 年 1 月
>
> **注意**：以上价格和额度信息可能随时间变化，请以官方页面为准。如需最新信息，请访问各方案的官方定价页面。Anthropic 融资信息基于公开媒体报道，实际数据以公司官方披露为准。

---

## AI 共有的不足和缺陷


## 数据与知识层面

- 训练数据不可追溯：来源不透明，更新不可再现，难以审计和监管（例：医疗对话数据混入论坛内容，错误建议无法追责）。
- 时效性缺失：回答容易引用过时信息，对实时数据与趋势不敏感（例：被问到最新利率或 CVE 时仍返回去年数据）。
- 事实幻觉：缺少可验证引用，虚构数字、文献和代码依然常见（例：编造论文标题、捏造 npm 包版本或接口字段）。
- 领域不均衡：中文、少数语言、专业术语、方言与长尾格式支持薄弱（例：中医方剂、法律条文引用常错位，粤语/方言指令被误解）。
- 偏见与刻板印象：历史数据里的歧视被放大，跨地区/行业使用易冲突本地法规与文化（例：求职推荐偏向性别刻板印象，触犯当地公平招聘规定）。
- 检索依赖：RAG 质量受索引时效、噪声和稀疏影响，无法一劳永逸解决事实性（例：索引未刷新导致产品文档已改版但回答仍指向旧参数）。

## 模型与算法局限

- 概率当确定性：缺少置信度表达，难以分级处理高风险场景（例：医疗问答把低概率诊断当肯定结论）。
- 长文本脆弱：上下文窗口有限，早期约束易被遗忘，推理链断裂（例：合同审阅漏掉前文免除条款）。
- 多模态裁决不足：图文冲突时缺少稳健的决策逻辑，新攻击面频出（例：图中文字写“禁止吸烟”但模型按图像场景回答“可以吸烟”）。
- 逻辑/数值/物理推理弱：多步因果、数量守恒、空间推理常犯低级错误（例：流水线产能计算时把单位搞混、数量不守恒）。
- 微调与漂移：定向微调易被脏数据污染，旧能力遗忘，新行为难预测（例：加入少量脏数据后把安全回复改成敏感输出）。
- 解释性薄弱：难给出因果链与可追溯证据，审核与合规成本高（例：风控拒绝原因无法溯源到具体特征或规则）。

## 系统与工程稳定性

- 输出波动与延迟：服务抖动、偶发崩溃，难以满足 SLA 与韧性要求（例：高峰期响应从 1s 抖到 20s+）。
- 格式不稳定：结构化输出常偏离协议，需要大量后处理与人工兜底（例：约定 JSON 却混入自然语言或缺字段）。
- 工具/函数调用脆弱：异常返回、超时、限流易让模型陷入死循环或空洞回复（例：重试未设上限导致 API 雪崩）。
- 成本不可控：冗长上下文、重试和插件调用叠加，账单常超预期（例：一次客服对话因多次检索与重试耗费数十倍预估成本）。
- 资源与供应链风险：GPU/TPU 供应紧张或权重合规受限会整体拖垮服务质量（例：突发算力抢占导致延迟飙升）。
- 监控与回溯不足：缺少在线评测、自动报警和可重放数据，问题多依赖用户投诉暴露（例：生产错误格式连续数小时未被发现）。
- 代码执行高风险：AI 生成或运行的脚本若无隔离，可能修改全局配置甚至误删磁盘（例：未在沙箱跑安装脚本导致 `rm -rf /` 误删服务器数据）。

## 安全、对抗与隐私

- 提示注入与越权：系统提示泄露、对抗样本和花式绕过依然高效（例：用户通过“忽略之前指令”拿到后台工具调用说明）。
- 隐私泄漏：模型记忆输入，日志和回答中可能暴露敏感信息（例：复述先前工单中的手机号或订单号）。
- 价值观与伦理红线：安全策略在多地区/行业下易失效，输出仍可能触碰红线（例：未屏蔽地区敏感话题或行业合规禁区）。
- 权限与会话隔离弱：多用户上下文混用，存在跨会话泄漏风险（例：多人协作时引用了其他用户的历史聊天内容）。
- 安全基线缺失：缺少灾难恢复、降级与熔断策略，异常时容易雪崩（例：上游检索宕机导致整体对话不可用，没有降级答案）。

## 产品化与运营挑战

- 需求澄清能力弱：遇到模糊请求时少主动追问，倾向冗长且模糊的回答（例：用户问“做个活动页”未反问目标、预算、设备渠道）。
- 用户体验漂移：同一问题答案随时间、状态或微小措辞变化大，难以做稳定运营（例：FAQ 一天内多次输出不同价格策略）。
- 人力成本高：提示词工程、对话状态管理和后处理需要持续人工投入（例：为保持 JSON 输出要不断调整 system prompt）。
- 反馈闭环慢：负面反馈难以被快速吸收，模型迭代周期长，线上修复滞后（例：用户举报错误后需多周才能进入新版本权重）。
- 规则对齐难：模型不了解业务 KPI、调用成本或限流策略，易触发额外成本或风险（例：忽略调用限额反复触发付费 API 导致账单爆表）。

## 典型高风险场景

- 医疗、金融、法律：事实幻觉、过时信息与偏见会直接影响合规和人身/财产安全（例：给出不符合当地指南的用药建议；引用废止条款）。
- 工业控制、自动驾驶、能源调度：延迟、抖动和边界条件下的不稳定推理难以满足安全要求（例：异常传感器数据时仍输出正常指令）。
- 内容审核、舆情与推荐：偏见、对抗样本与格式不稳定会放大审核漏报或误报（例：被对抗样本绕过暴恐文本检测）。
- 代码与配置生成：忽略运行时依赖、版本兼容与安全基线，可能引入漏洞（例：生成的依赖存在已知 CVE，或配置未加鉴权）。
- 客服与多轮对话：错误累积、缺乏自我纠错和澄清，容易形成错误链（例：一次误解订单号后续全程使用了错误上下文）。

## 人的主导作用与落地原则

- 人定流程，机做辅助：关键环节先定义人类决策流程，AI 仅做草稿、对照或检索；最终决策与签字由人负责（例：招投标由人定评分表，AI 只初筛标书）。
- 明确“人类监督”角色：指定责任人审核高风险输出（医疗/金融/法律/自动驾驶/安全变更），建立双人复核或结对审查（例：医疗报告需主治与质控双人签字，AI 草稿仅供参考）。
- 人保准入，机做建议：让 AI 给选项而非直接执行，审批、下单、推送、发布、调度等动作必须经过人工确认（例：AI 生成折扣方案，运营手工确认后再上线）。
- 人控知识，机用引用：知识库由人维护版本与生效时间，AI 只能引用，不得自行增删；更新流程需人工验收与回溯标签（例：客服 FAQ 由知识管理员审核后上线，并标注生效日期）。
- 人验安全，机跑流程：安全策略、脱敏规则、合规模板由人制定；AI 输出必须过人设的校验（格式、术语、敏感词、地区合规）（例：代码生成需通过人写的安全扫描规则后才能提交）。
- 人管成本，机限配额：费用预算、配额和重试上限由人配置，AI 调用受限，超限直接降级或中止（例：每日检索调用超过配额时自动转为摘要模式并通知负责人）。
- 人做澄清，机做收敛：对模糊需求，先由人或前置问卷澄清核心参数，再让 AI 生成；避免 AI 自行假设（例：活动页需求先收集预算和渠道，再让 AI 出页面草稿）。
- 人设指标，机供度量：业务 KPI、安全阈值、可解释性要求由人定义；AI 需要输出置信度/引用/可追溯数据供人审阅（例：风控模型需附置信度和引用规则，审核员决定是否拒绝）。
- 人定迭代节奏：线上反馈、红队结果与误报/漏报统计由人评审，决定是否更新提示词、检索索引或模型版本（例：每周复盘高风险对话，人工决定是否切换新模型）。

## 应对建议（简要）

- 数据：做好来源审计、去偏与时效刷新，检索链路监控召回/精排质量（例：每周重建索引并人工抽检医疗条目）。
- 模型：提供置信度或自评估，限制长上下文依赖，针对关键任务做专项评测（例：财报问答需展示置信度并通过专门算例测试）。
- 系统：加熔断、降级和重试上限，强制结构化输出校验，建立在线监控与回溯（例：工具调用超时即降级为静态答案并记录重放日志）。
- 安全：定期红队，对抗样本库更新，隔离系统提示与用户输入，保护日志与隐私（例：每月红队拉通提示注入用例，更新过滤策略）。
- 运营：标准化提示与模板，AB/灰度发布，快速回滚通道，建立反馈闭环与标签体系（例：新客服提示先灰度 5% 流量，异常立即回滚）。

把模型当作不稳定的外部依赖来治理：先明确人类的职责、审批和复核流程，再让 AI 进入关键路径；留足监控、评测、韧性与人工兜底的预算，确保“人是决策者，AI 是工具”。

---

## AI 编程方案选型指南


## 一、方案概述

本文档旨在为公司提供全面的 AI 编程工具选型参考，涵盖国际主流与国产优秀方案，从订阅服务、IDE 工具到插件扩展，帮助决策者根据团队需求、预算和使用场景做出最优选择。

---

## 二、详细对比文档

对于更深入的模型和工具对比分析，可参考以下文档：

| 文档 | 说明 | 链接 |
| ---- | ---- | ---- |
| **国外顶尖编程模型选型建议书** | Claude Opus 4.5、GPT-5.2、Gemini 3 Pro 三大模型的深度对比，含价格、刷新周期、额度用完后如何继续使用 | [international-ai-models-comparison.md](./international-ai-models-comparison.md) |
| **AI 编程工具选型建议书** | GLM-4.7 + Claude Code CLI 最佳组合，Qoder vs Cursor IDE 对比，含刷新周期和额度限制详解 | [qoder-vs-glm47-cursor-claude-comparison.md](./qoder-vs-glm47-cursor-claude-comparison.md) |

> **核心要点**：
> - **刷新周期对比**：GLM-4.7/ChatGPT 每 **5 小时**（最快）> Gemini Code Assist 每 **日** > GitHub Copilot/Qoder/Cursor 每 **月** > Claude Code 每 **7 天**（最慢）
> - **额度用完后方案**：等待刷新周期 / 使用 API KEY 按量计费 / 切换其他订阅账号 / 升级更高版本套餐

---

## 三、核心平台特点总结

- **AI 编程能力排行**：可随时查看 **[LLM Stats](https://llm-stats.com/)** 获取最新模型榜单与分数，用于快速对比模型迭代效果。
- **综合榜单（能力/价格/上下文）**：如需更全面的横向对比，可参考 **[Vellum Leaderboard](https://www.vellum.ai/llm-leaderboard)**。
- **真实工程 Bug 修复基准**：SWE-bench（含真实 GitHub Issues）可参考 **[官方网站](https://www.swebench.com)**。
- **国产模型评测榜单**：OpenCompass（国内权威评测体系之一）可查看 **[排行榜](https://rank.opencompass.org.cn/home)**。
- **国产模型国际榜单入口**：AI Rank 汇总多家国际评测的国产模型成绩，可访问 **[AI Rank](https://airank.dev/)**。
- **上海人工智能实验室-国产模型评测项目**：开源评测框架 OpenCompass（国人自研，涵盖多维度对比）仓库见 **[github.com/open-compass/opencompass](https://github.com/open-compass/opencompass)**。

### 2.1 国际主流 AI 平台

#### **ChatGPT (OpenAI)**

- **核心优势**: GPT-5.2 在 SWE-Bench Pro 达到 55.6%，o1 pro 模式专为复杂编程优化
- **适用场景**: Plus 版 ($20/月) 适合个人开发者，Pro 版 ($200/月) 适合高强度专业用户，API 调用额度高 15-20 倍
- **评价**: o 系列模型在编程、数学、科学问题求解方面表现突出，业界认可度高

**ChatGPT 订阅梯度（以官网为准）**

| 功能                         | Plus ($20/月)                        | Pro ($200/月)                                     | Team ($25/人/月，≥5 人)                                |
| ---------------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
| 价格                         | $20/月                               | $200/月                                           | $30/人/月（按月） $25/人/月 （按年）（起售 5 席） |
| 模型访问                     | GPT-5.2 / GPT-5.2 mini，o1-mini 轻量 | GPT-5.2 / GPT-5.2 mini，o1-pro & o3-mini 更高配额 | GPT-5.2 / GPT-5.2 mini，团队共享配额                   |
| 高级推理                     | o1-mini 低频                         | o1-pro 高频、长上下文                             | o1-pro 团队配额，可分配席位                            |
| 上下文/文件                  | 更高文件大小与上下文                 | 最高文件大小/上下文，适合长文档与代码库           | 与 Pro 类似，可团队共享                                |
| 代码执行（Code Interpreter） | 更高并发与用量                       | 最高并发/用量，适合数据分析与脚本                 | 团队并发/用量共享                                      |
| 自定义工具/Memory            | ✓                                    | ✓（更高容量）                                     | ✓（团队共享，权限可管控）                              |
| 团队/组织                    | 个人订阅                             | 可与 Team/Enterprise 联动                         | 席位制，含团队管理/审计入口                            |
- 定价计算: [OpenAI Pricing](https://openai.com/pricing) / [API Pricing](https://openai.com/api/pricing)

#### **Claude (Anthropic)**

- **核心优势**: Claude Code 编程能力业界顶尖，开发者用其完成 95% 编码工作，效率提升 3 倍以上
- **适用场景**: Pro 版 ($20/月) 提供 Sonnet 模型，Max 版 ($100/$200/月) 在 IDE 中独家使用 Opus 4 模型
- **评价**: 11.5 万开发者使用，单周处理 1.95 亿行代码，被评价为 "超值" 的编程助手

**Claude 订阅梯度（以官网为准）**

| 功能                 | Pro ($20/月)                      | Team 标准席位 ($25/人/月，≥5 人)                       | Team Premium 席位 ($150/人/月)        |
| -------------------- | --------------------------------- | ------------------------------------------------------ | ------------------------------------- |
| 价格                 | $20/月                            | $30/人/月（按月） $25/人/月 （按年）（起售 5 席） | $150/人/月                            |
| 模型访问             | Sonnet 高额度，Opus/Opus 预览限量 | Sonnet/Opus 高额度，优先新模型                         | Sonnet/Opus 高额度 + Premium 优先队列 |
| 消息额度             | ~5x 免费用量、优先队列            | 团队更高用量、共享池                                   | 更高配额，适合高频审查/重构           |
| 上下文/文件          | 更长上下文/文件上传               | 最高上下文/文件上限                                    | 最高上限，适合跨大仓库重构            |
| Artifacts / Projects | ✓                                 | ✓（团队项目/共享空间）                                 | ✓（Premium 同享）                     |
| 管理与审计           | ✗                                 | 管理后台、成员管理、单点登录                           | 管理后台、审计、Premium 支持          |
- 定价计算: [Claude Pricing](https://claude.com/pricing)

#### **Gemini Pro 3 / Flash (Google)**

- **核心优势**: 长上下文（百万级，具体以官方发布为准），工具调用与代码补全兼顾，多模态（文本/图像/音频）理解；Flash 版本主打低延迟与低成本，适合实时交互与批量脚本。
- **适用场景**: Pro 3 用于复杂推理、跨文件重构、代码审查；Flash 用于低延迟补全、对话式问答、批量生成；AI Pro/Ultra 套餐对创意多模态（图生图、视频生成）和深度研究额度提升明显。
- **计费/托管**: Google AI Studio 提供订阅（AI Pro $20/月，AI Ultra $250/月，均含免费试用期）与免费层，企业可通过 Vertex AI 获得 VPC-SC、CMEK、审计与私有服务访问（以官方定价为准）；部分功能限美国地区。
- **评价**: 在推理速度/性价比上优势明显，结合 Vertex AI 的安全与合规能力适合对合规有要求的团队；AI Ultra 独享 Deep Think / Project Mariner，适合重度研究或创意团队。

**Gemini Pro 3 订阅梯度**

| 功能                      | AI Pro ($20/月)    | AI Ultra ($250/月)      |
| ------------------------- | ------------------ | ----------------------- |
| 价格                      | $20/月（首月免费） | $250/月（前 3 月 $125） |
| Gemini 3 Pro 对话         | 更高权限           | 最高用量                |
| Deep Think                | ✗                  | ✓（Ultra 专属）         |
| Gemini Agent              | ✗                  | ✓（仅限美国）           |
| Deep Research（深度研究） | 20 份/天           | 200 份/天               |
| Gemini Code Assist/CLI    | 更高上限           | 最高上限                |
| Jules（程式设计代理）     | 更高额度           | 最高额度                |
- 定价计算: [Google AI Studio Pricing](https://ai.google.dev/pricing) / [Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing)
| Project Mariner           | ✗                  | ✓（抢先体验，仅限美国） |

**ChatGPT vs Claude vs Gemini Pro 3 对比（Team 编码场景）**

| 维度          | ChatGPT                              | Claude                               | Gemini Pro 3                              |
| ------------- | ------------------------------------ | ------------------------------------ | ----------------------------------------- |
| 起步价格      | Plus $25/人/月 (按年)                | Pro $25/人/月 (按年)                 | AI Pro $20/月                             |
| 推理/代码     | o1-pro 强推理，Code Interpreter 稳定 | Sonnet/Opus 代码审查与长上下文表现佳 | Pro 3 长上下文，推理性价比高，纯代码稍弱  |
| 长上下文/文件 | Pro 版最高上下文与文件上传           | Team 版最高上下文与团队共享文件      | Ultra 更高上下文，适合跨文件重构          |
| 代码工具/代理 | Code Interpreter，工具/Memories      | Artifacts/Projects，团队协作         | Gemini Code Assist/CLI，Jules（编程代理） |
| 适用场景      | 复杂编码/数据分析/脚本               | 代码审查、跨文件重构、团队配合       | 长上下文重构 + 研究/Agent 编排            |

### 2.2 国产 Coding Plan 平台

#### **GLM 智谱清言 (智谱 AI)**

- **核心优势**: GLM-4.6 代码能力对齐 Claude Sonnet 4，国内最强 Coding 模型，token 消耗比前代少 30%
- **性价比**: 最低 ¥40/月，约 Claude 价格的 1/7，性能达 Claude 的 9/10
- **评价**: 在 CC-Bench 等 7 大权威测试中表现卓越，真实编程测试中超过 Claude Sonnet 4
- **定价**: [bigmodel.cn/pricing](https://bigmodel.cn/pricing)

#### **MiniMax M2**

- **核心优势**: 专为 Agent 和代码而生，SWE-bench 冠军 (44% 成功率超 GPT-5 Codex)，价格仅 Claude 的 8%，速度是其 2 倍
- **技术参数**: 100 亿激活参数，2300 亿总参数，20 万+ 上下文窗口
- **评价**: 开源排名第一，前端设计和交互方案表现尤为出色
- **定价**: [MiniMax 定价](https://platform.minimaxi.com/docs/guides/pricing?key=68aec7e84c75b9c918ccd10d)

#### **Kimi K2 Thinking (月之暗面)**

- **核心优势**: 万亿参数混合专家架构，支持 256K 上下文，能执行 200-300 次连续工具调用
- **技术特点**: 原生 INT4 量化，低延迟模式下 2 倍加速且无损性能
- **评价**: NIST 评估为当时中国最强 AI 模型，在 SWE-Multilingual 得分 61.1%
- **定价**: [Kimi 定价](https://kimi.moonshot.cn/pricing)

#### **通义千问 (阿里云 Qwen 系列)**

- **最新模型族**: Qwen3（通用）/Qwen3-Coder（代码）/Qwen3-VL（多模态）/Qwen-Long（超长上下文）及轻量推理款 QwQ；覆盖推理、代码、视觉与长文档需求
- **核心能力**: 原生函数/工具调用、检索/联网、代码补全与跨文件重构，多模态理解（图文/表格/公式），长上下文版本可支持跨文件与长文档分析
- **适用场景**: 百炼平台一键编排多模型与工具，适合电商/内容/客服/代码等多轮推理场景；长文档与多模态（设计稿还原、表格解析）场景表现稳健
- **计费/托管**: 百炼提供按量/订阅与企业版（VPC、审计、CMEK、数据不出境），支持私有化或混合云部署，便于满足国内合规
- **评价**: 中文语料和行业场景打磨成熟，工程化与性价比兼顾，是国内团队可长期依赖的主力模型
- **定价**: [百炼模型市场-Qwen](https://bailian.console.aliyun.com/#/model-market/detail/qwen-max)

#### **火山方舟 (豆包 Doubao-Seed-Code)**

- **核心优势**: 国内首个支持视觉理解的编程模型，可根据 UI 设计稿/截图生成代码，在 TRAE 环境中 SWE-Bench Verified 达 78.80% (SOTA)
- **成本优势**: 业界综合成本降低 62.7%，国内最低价，同样任务成本仅为 Claude 的 8%，GLM 的 44%
- **评价**: 前端页面复刻能力 "遥遥领先"，兼容 Anthropic API，易于迁移
- **定价**: [Doubao 定价](https://www.volcengine.com/product/doubao)

### 2.3 IDE 与开发环境

#### **Cursor**

- **市场地位**: 估值 99 亿美元，年化收入 5 亿美元且每两月翻番，行业领导者
- **核心功能**: 预测式代码补全 (预测 5-10 行)、跨文件重构引擎、交互式调试
- **评价**: v1.0/v1.1 新增 BugBot 审查、Background Agent、Memory 能力，社区生态最完善

#### **GitHub Copilot**

- **核心优势**: 与 GitHub 深度集成，生态完善，2025 年 12 月新增组织级代码审查功能
- **Premium Requests**: Pro 版 300 次/月，Pro+ 版 1,500 次/月，超量 $0.04/次
- **评价**: 超时率从 4.3% 降至 1.1%，稳定性显著提升，适合 GitHub 重度用户

#### **Windsurf (Codeium)**

- **技术创新**: 全球首个 AI Flow 范式 IDE，Cascade 技术实现多步骤协同，Supercomplete 预测高层意图
- **定价优势**: 免费版 25 积分/月，Pro 版 $15/月 (500 积分)，可免费使用 GPT-4o 和 Claude 3.5 Sonnet
- **评价**: 上下文理解能力优于 Cursor，适合需要深度代码库理解的团队

#### **Trae (字节跳动)**

- **本土优势**: 中国首个 AI 原生 IDE，原生中文支持，配置 Doubao-1.5-pro/DeepSeek R1/V3
- **核心功能**: Builder 模式 (从零构建项目)、Solo 模式 (全流程自动化)
- **评价**: 目前完全免费，效率提升 300%，但低配置环境下性能问题明显

#### **Qoder（阿里）**

- **定位**: 阿里推出的全栈 AI IDE，强调跨文件重构与代码审查
- **核心功能**: 长上下文补全、Agent 式任务分解、项目级搜索与重构、终端/工具调用
- **定价**: Pro+ $30/月，Ultra $100/月（更高上下文与 Agent 并发）

#### **Kiro (AWS)**

- **核心特点**: 规格驱动开发 (Spec-Driven)，强制 "先计划后构建"，Agent Hooks 自动化触发器
- **技术架构**: 专用 Claude Sonnet 3.7/4.0 模型
- **评价**: 适合企业级项目管理和流程规范化，目前公测阶段免费

### 2.4 VSCode 插件

#### **Augment**

- **核心优势**: SWE-Bench Verified 冠军 (65.4%)，20 万 token 上下文窗口，基于 Claude Sonnet 4
- **功能特点**: Agent 智能体模式、持久记忆学习编码风格、支持多模态输入 (截图/Figma)
- **多 IDE 支持**: JetBrains、VS Code、GitHub、Slack、Vim 全覆盖
- **定价**: 新用户半月免费试用，之后 $60/月

---

## 三、选型建议

### 3.0 不同规模团队的决策要点

- **提效优先结论**：追求最佳 AI 编程提效时，优先选 Claude Code（AI 工程化最完善，$100/月足够覆盖重度开发）；成本敏感可选 codex（工程化稍弱，约 $20/月满足多数场景）。
- **多模态优势**：Gemini Pro 3 在图像/视觉理解上领先，适合涉及设计稿还原或多模态需求的团队，纯编程能力弱于 Claude Code/codex。
- **极致降本路径**：在 SaaS 订阅外，还可组合开源项目自建中转站与号池，进一步压缩调用成本（需评估合规与运维成本）。
- **个人 / 1-10 人**：优先 ChatGPT Plus、Claude Pro、Cursor Pro（或 Windsurf Free/Pro）+ Copilot Pro；关注易用与成本封顶。
- **10-50 人**：Cursor Pro/Pro+ + Claude Max / ChatGPT Pro；国内可选 Doubao Lite/Pro + Windsurf Pro；统一 1-2 款 IDE，建立提示词与代码片段库。
- **50-200 人**：国际（Cursor Pro+/Ultra + Claude Max / ChatGPT Pro）+ 国内（Doubao Pro 或 GLM Pro/Max + Windsurf/Trae）；开始启用 SSO、审计、内网代理，分团队额度管理。
- **200-300 人（大型研发）**：国际+国内双栈并行，企业版或 Team/Business 版启用 SSO/SCIM、审计日志、VPC/专线；指标化复盘（拒答率、幻觉率、代码审查命中率）。
- **300 人以上 / 跨境上市公司**：必须满足 SOX/内部控制、数据主权、GDPR/CCPA、渗透与安全评估；采用企业合同（DPA/BAA/SOW），双 Region 数据隔离，DLP + 本地检索，关键产出需人工复核留痕。
- **共通动作**：统一 IDE/插件、分级仓库访问、敏感项目禁传公有端点、月度成本与质量复盘，逐步升级模型与额度。

### 3.1 按预算分类

- **低成本方案**: MiniMax M2 (¥29 起)、火山方舟 (¥40 起)、Trae (免费)
- **中等预算**: GLM (¥40 起)、Windsurf Pro ($15)、GitHub Copilot Pro ($10)
- **高端方案**: Cursor Ultra ($200)、ChatGPT Pro ($200)、Claude Max ($200)

### 3.2 按使用场景分类

- **个人开发者**: ChatGPT Plus、Claude Pro、GLM Lite
- **中小团队**: Cursor Pro、Trae、Windsurf、MiniMax
- **企业级团队**: Cursor Teams、GitHub Copilot Enterprise、Kiro、Augment
- **前端开发优先**: 火山方舟 (视觉理解)、MiniMax M2
- **中文环境优先**: Trae、GLM、火山方舟、Kimi

### 3.3 按技术栈分类

- **VSCode 生态**: Augment、Trae、Windsurf 插件
- **JetBrains 用户**: Augment、Windsurf 插件
- **GitHub 重度用户**: GitHub Copilot
- **多语言项目**: Cursor、Kimi K2、GLM-4.6

### 3.4 推荐组合示例（多规模适用）

| 需求                    | 推荐组合                                                 | 说明                                        |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------- |
| 代码生成 + 评审（国际） | Cursor Pro+/Ultra + Claude Max / ChatGPT Pro             | 大上下文 + 强代理调度，覆盖多语言与复杂重构 |
| 代码生成 + 评审（国内） | Windsurf Pro 或 Trae + Doubao Seed-Code / GLM-4.6        | 便于内网代理与中文语境，成本可控            |
| IDE 轻量补全            | GitHub Copilot Business/Enterprise                       | 统一 GitHub 权限与审计，团队管理成熟        |
| Agent 式自动化          | Cursor Background Agent / Trae Solo 模式 / MiniMax Agent | 适合批量脚手架、重构、测试生成              |
| 合规/隔离               | OpenAI/Anthropic Enterprise 或 Doubao/GLM 私有化选项     | 支持 SSO、审计、VPC/专线、模型封装          |

### 3.5 模型与方案汇总表（选型速览）

| 类别        | 代表模型/方案                           | 适合规模   | 主要优势                            | 价格级别 | 合规要点                            |
| ----------- | --------------------------------------- | ---------- | ----------------------------------- | -------- | ----------------------------------- |
| 国际通用    | ChatGPT Pro / Claude Max                | 个人-200人 | 全能生成、复杂推理、API 额度高      | $$$      | 开启 SSO/日志控制；敏感仓库少量上传 |
| 国际企业    | OpenAI/Anthropic Enterprise             | 200人以上  | 合规合同（DPA/BAA）、审计、私有端点 | $$$$     | 支持专线/VPC、数据隔离、可签 SOW    |
| 国内主力    | Doubao Seed-Code / GLM-4.6              | 10-300人   | 中文/视觉理解强，成本低             | $$       | 企业版支持专线，需国内数据合规      |
| 性价比      | MiniMax M2 / Kimi K2                    | 1-200人    | 价格低、长上下文                    | $-$$     | 避免敏感代码上传公有端点            |
| IDE/Agent   | Cursor Pro+/Ultra / Windsurf Pro / Trae | 10-300人   | IDE 深度集成，Agent/Flow 协同       | $-$$$    | 企业代理、最少遥测、私有仓库索引    |
| 补全/审查   | GitHub Copilot Business/Enterprise      | 10-300人   | GitHub 权限与审计成熟               | $$       | 绑定组织 SSO/SCIM，禁外发私仓代码   |
| VSCode 插件 | Augment                                 | 10-200人   | 大上下文，Agent/多模态              | $$       | 控制上传范围与日志，必要时本地检索  |

---

## 订阅计划

### ChatGPT

| **套餐等级**      | **月度**      |
| ----------------- | ------------- |
| **Plus**          | $20           |
| **Pro**           | $200          |
| **Business/Team** | $30/person    |
| **Enterprise**    | Sales Contact |

### Claude

[Pricing](https://platform.claude.com/docs/en/about-claude/pricing)

| **套餐等级** | **月度** |
| ------------ | -------- |
| **Pro**      | $20      |
| **Max 5x**   | $100     |
| **Max 20x**  | $200     |

## IDE/插件

## Coding Plan

提供 API，可接入 Claude Code，Cline 和 Chat 软件中使用。

### GLM (z.ai)(智谱清言)

[Pricing](https://bigmodel.cn/glm-coding)

最新模型：GLM-4.6 GLM-4.6V

| **套餐等级** | **月度** | **季度** | 年度  | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| ------------ | -------- | -------- | ----- | ------------------------ | -------------------- |
| **Lite**     | ¥40      | ¥120     | ¥480  | ~120 Prompts             | Claude Pro 的 3 倍   |
| **Pro**      | ¥200     | ¥600     | ¥2400 | ~600 Prompts             | Lite 的 5 倍         |
| **Max**      | ¥400     | ¥1200    | ¥4800 | ~2400 Prompts            | Pro 的 4 倍          |

### MiniMax M2

[Pricing](https://platform.minimaxi.com/docs/pricing/coding-plan)
最新模型：MiniMax M2

| **套餐等级** | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度**    |
| ------------ | -------- | -------- | -------- | ------------------------ | ----------------------- |
| **Starter**  | ¥29      | ¥87      | ¥348     | 40 Prompts               | 约 Claude Pro 的 1 倍   |
| **Plus**     | ¥49      | ¥147     | ¥588     | 100 Prompts              | 约 Claude Pro 的 2.5 倍 |
| **Max**      | ¥119     | ¥357     | ——       | 300 Prompts              | 约 Claude Pro 的 7.5 倍 |

## Kimi

[Pricing](https://www.kimi.com/membership/pricing)
最新模型：Kimi K2 Thinking

| **套餐等级**   | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| -------------- | -------- | -------- | -------- | ------------------------ | -------------------- |
| **Andante**    | ¥49      | ——       | ——       | 1024 Prompts             | ——                   |
| **Moderato**   | ¥99      | ——       | ——       | 2048 Prompts             | ——                   |
| **Allegretto** | ¥119     | ——       | ——       | 7168 Prompts             | ——                   |

## 火山方舟(豆包)

[Pricing](https://www.volcengine.com/activity/codingplan)
最新模型：Doubao-Seed-Code DeepSeek-V3.2

| **套餐等级** | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| ------------ | -------- | -------- | -------- | ------------------------ | -------------------- |
| **Lite**     | ¥40      | ¥120     | ¥480     | ~120 Prompts             | Claude Pro 的 3 倍   |
| **Pro**      | ¥200     | ¥600     | ¥2400    | ~600 Prompts             | Lite 的 5 倍         |

## IDE

### Cursor

[Pricing](https://www.cursor.com/pricing)

| **套餐** | **月度 (USD)** | **额度**                                                   |
| -------- | -------------- | ---------------------------------------------------------- |
| Hobby    | $0             | 1 周试用 + 有限 Agent/Tab                                  |
| Pro      | $20            | 无限 Tab/Auto + $20 frontier model 额度 (~225 次 Sonnet 4) |
| Pro+     | $60            | Pro 的 3 倍模型使用额度                                    |
| Ultra    | $200           | Pro 的 20 倍模型使用额度                                   |
| Teams    | $40/人         | Pro 额度 + 团队管理                                        |

### Github Copilot

[Pricing](https://github.com/features/copilot/plans)

| **套餐**   | **月度 (USD)** | **额度**                                          |
| ---------- | -------------- | ------------------------------------------------- |
| Free       | $0             | 2,000 completions/月 + 50 premium requests/月     |
| Pro        | $10            | 无限 completions + 300 premium requests/月        |
| Pro+       | $39            | 无限 completions + 1,500 premium requests/月      |
| Business   | $19/人         | 无限 completions + 300 premium requests/用户/月   |
| Enterprise | $39/人         | 无限 completions + 1,000 premium requests/用户/月 |

#### Winsurf

[Pricing](https://windsurf.com/pricing)

| **套餐**   | **月度 (USD)** | **额度**            |
| ---------- | -------------- | ------------------- |
| Free       | $0             | 25 credits/月       |
| Pro        | $15            | 500 credits/月      |
| Teams      | $30/人         | 500 credits/人/月   |
| Enterprise | 联系销售       | 更高额度 + 企业功能 |

#### Trae

[Pricing](https://www.trae.ai/pricing)
[Billing](https://docs.trae.ai/ide/billing)

| **套餐** | **月度 (USD)** | **额度**                  |
| -------- | -------------- | ------------------------- |
| Free     | $0             | 基础功能（有限额度）      |
| Pro      | $10            | 新用户首月 $3（原价 $10） |

#### Kiro

[Pricing](https://kiro.dev/pricing)

| **套餐**   | **月度 (USD)** | **额度**                               |
| ---------- | -------------- | -------------------------------------- |
| Free       | $0             | 50 credits                             |
| Pro        | $20            | 1,000 credits/月（超量 $0.04/credit）  |
| Pro+       | $40            | 2,000 credits/月（超量 $0.04/credit）  |
| Power      | $200           | 10,000 credits/月（超量 $0.04/credit） |
| Enterprise | 联系销售       | 自定义额度 + 企业功能                  |

### VSCode 插件

#### Augment

[Pricing](https://augmentcode.com/pricing)

| **套餐**   | **月度 (USD)** | **额度**              |
| ---------- | -------------- | --------------------- |
| Indie      | $20            | 40,000 credits/月     |
| Standard   | $60            | 130,000 credits/月    |
| Max        | $200           | 450,000 credits/月    |
| Enterprise | 联系销售       | 自定义额度 + 企业功能 |

## 共享方案

### New API

[GitHub](https://github.com/QuantumNous/new-api)

若上方的 coding plan 提供了 apikey 的方式，则可以将 apikey 添加到 new api 中进行聚合，然后分发出去。

### Claude Relay Service

[GitHub](https://github.com/Wei-Shaw/claude-relay-service)

若没有直接提供 key，例如 Claude Code, Codex 等，则可以部署 CRS 来登录 Claude Code 和 OpenAI 的账号来分发

## 注意点

Claude Code 由于环境要求严格，容易封号，所以部署环境要至少需要使用美国家庭宽带代理，否则容易封号 (虽然会退款)。

## 促销活动

- 当前 chatgpt 的 business 方案存在 $0 一个月，具有 5 个席位的 team 方案，市面上会有 ￥10/个席位并提供质保的商家，结束时间取决于 openai 的官方政策。

- GLM 存在首年/季度/年优惠，可使用多个账号购买并通过上方的方式共享和分发。

### Claude code/Codex 中转站

当前市面上存在 Claude Code/Codex 中转站，以 Claude Code 为例，价格普遍在每刀 ￥0.3-￥1 之间。由于价格计算涉及倍率/中转站内部计费规则，故不列出。

---

## AI Agent（智能体）


## 概述

**AI Agent（人工智能智能体）** 是一个能够**自主感知环境、做出决策并执行行动**的 AI 系统。与传统的聊天式 AI 不同，Agent 可以：

- 主动调用工具
- 规划多步骤任务
- 处理复杂的工作流
- 在失败时自动重试

> **核心特点**：自主性、交互性、反应性、主动性

---

## 核心概念

### 1. Agent 的定义

**Agent** 是能够：

1. **感知** (Perceive)：获取环境信息
2. **推理** (Reason)：分析情况并制定计划
3. **行动** (Act)：执行具体操作
4. **学习** (Learn)：从反馈中改进

### 2. Agent 与 Chatbot 的区别

| 特性 | Chatbot | AI Agent |
| ---- | ------- | -------- |
| **交互方式** | 问答式 | 任务导向 |
| **主动性** | 被动响应 | 主动规划 |
| **工具使用** | 有限 | 丰富 |
| **任务复杂度** | 单步任务 | 多步骤任务 |
| **记忆能力** | 会话级 | 长期记忆 |
| **自主决策** | 无 | 有 |

---

## Agent 的架构

### 基本架构

```
┌─────────────────────────────────────────────────────────┐
│                    AI Agent 架构                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────┐     ┌─────────┐     ┌─────────┐          │
│  │  输入    │ ──▶│  推理    │ ──▶│  输出    │          │
│  │ Input   │     │ Reasoning│     │ Output  │          │
│  └─────────┘     └────┬────┘     └─────────┘          │
│                       │                                 │
│                       ▼                                 │
│              ┌─────────────┐                           │
│              │   工具调用   │                           │
│              │   Tools     │                           │
│              └─────────────┘                           │
│                       │                                 │
│                       ▼                                 │
│              ┌─────────────┐                           │
│              │   环境反馈   │                           │
│              │  Feedback   │                           │
│              └─────────────┘                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 核心组件

#### 1. 规划模块 (Planning)

- 任务分解
- 步骤排序
- 资源分配
- 时间估算

#### 2. 记忆模块 (Memory)

- 短期记忆（当前会话）
- 长期记忆（向量存储）
- 上下文管理
- 知识检索

#### 3. 工具模块 (Tools)

- 文件操作
- API 调用
- 命令执行
- 数据库查询

#### 4. 反思模块 (Reflection)

- 结果验证
- 错误处理
- 策略调整
- 重试机制

---

## Agent 的类型

### 1. 单 Agent 系统

由一个 Agent 完成所有任务：

```
┌─────────────────┐
│    Agent       │
│  ┌───────────┐  │
│  │ Planning  │  │
│  │ Memory    │  │
│  │ Tools     │  │
│  │ Action    │  │
│  └───────────┘  │
└─────────────────┘
```

**特点**：
- 实现简单
- 适合单领域任务
- 容易调试

### 2. 多 Agent 系统

多个 Agent 协同工作：

```
┌─────────────────────────────────────────────────────────┐
│                   Multi-Agent System                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│  │  Planner │ ──▶│  Coder   │ ──▶│  Tester  │         │
│  │  Agent   │    │  Agent   │    │  Agent   │         │
│  └──────────┘    └──────────┘    └──────────┘         │
│       │               │               │                │
│       └───────────────┴───────────────┘                │
│                       ▼                                 │
│              ┌──────────────┐                           │
│              │ Coordinator  │                           │
│              │    Agent     │                           │
│              └──────────────┘                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

**特点**：
- 专业化分工
- 可并行处理
- 适合复杂任务

**常见角色**：

| Agent 角色 | 职责 |
| ---------- | ---- |
| **Planner** | 任务规划、分解 |
| **Coder** | 代码生成、修改 |
| **Reviewer** | 代码审查、验证 |
| **Tester** | 测试用例生成 |
| **Debugger** | 问题定位、修复 |
| **Documenter** | 文档生成 |

### 3. 层级 Agent 系统

Agent 之间存在上下级关系：

```
┌─────────────────────────────────────────────────────────┐
│              Hierarchical Agent System                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌───────────────────────────────────────┐             │
│  │        Manager Agent (L1)             │             │
│  │     任务分配、进度监控、协调          │             │
│  └─────────────┬─────────────────────────┘             │
│                │                                         │
│     ┌──────────┼──────────┐                             │
│     ▼          ▼          ▼                             │
│  ┌──────┐ ┌──────┐ ┌──────┐                           │
│  │Coder ││Tester││Doc   │ (L2)                         │
│  │Agent ││Agent ││Agent │                              │
│  └──────┘ └──────┘ └──────┘                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## 主流 Agent 框架

### 1. LangChain Agent

```python
from langchain.agents import create_openai_functions_agent
from langchain.tools import Tool

# 定义工具
tools = [
    Tool(
        name="calculator",
        func=lambda x: eval(x),
        description="执行数学计算"
    )
]

# 创建 Agent
agent = create_openai_functions_agent(
    llm=chat_model,
    tools=tools,
    prompt=prompt
)
```

### 2. AutoGen

```python
from autogen import AssistantAgent, UserProxyAgent

# 创建 Agent
assistant = AssistantAgent(
    name="assistant",
    llm_config={"model": "gpt-4"}
)

user_proxy = UserProxyAgent(
    name="user_proxy",
    code_execution_config={"work_dir": "coding"}
)

# 启动对话
user_proxy.initiate_chat(
    assistant,
    message="计算斐波那契数列的第 10 项"
)
```

### 3. Claude Code Task Agent

```typescript
// 使用 Claude Code 的子代理

const result = await Task({
  description: "分析项目代码结构",
  subagentType: "explore",
  model: "claude-opus-4-5"
});
```

### 4. Cursor Composer

Cursor 的 Agent 系统：
- **Composer**：多步骤任务执行
- **Background Agent**：后台处理
- **Multi-Agent Interface**：并行多智能体

---

## Agent 的设计模式

### 1. ReAct (Reasoning + Acting)

```
Thought (思考) → Action (行动) → Observation (观察) → Thought (思考) → ...
```

**示例**：
```
Thought: 我需要读取文件内容
Action: ReadFile(path="src/main.js")
Observation: 读取到 100 行代码
Thought: 我看到了问题所在
Action: EditFile(...)
```

### 2. Chain of Thought

逐步推理，展示思考过程：

```
问题：用户报告登录失败

思考步骤：
1. 检查认证逻辑
2. 查看日志文件
3. 验证 API 配置
4. 定位问题原因
```

### 3. Plan-and-Execute

先规划再执行：

```
1. 规划阶段：
   - 分析需求
   - 制定计划
   - 分解任务

2. 执行阶段：
   - 按步骤执行
   - 记录进度
   - 处理异常
```

### 4. Self-Refine

自我反思和改进：

```
1. 生成初始方案
2. 自我审查
3. 识别问题
4. 改进方案
5. 重复 2-4
```

---

## Agent 的最佳实践

### 1. 明确目标

- 清晰定义任务边界
- 设定成功标准
- 明确输出格式

### 2. 工具设计

- 工具功能单一
- 输入输出明确
- 错误处理完善

### 3. 记忆管理

- 合理设置上下文窗口
- 使用向量存储长期记忆
- 定期清理无关信息

### 4. 安全考虑

- 限制可执行的操作
- 实施权限控制
- 记录所有行动

### 5. 可观测性

- 记录决策过程
- 监控执行状态
- 追踪资源使用

---

## Agent 的应用场景

| 场景 | Agent 类型 | 说明 |
| ---- | ---------- | ---- |
| **代码生成** | Coder Agent | 生成、修改代码 |
| **代码审查** | Reviewer Agent | 审查代码质量 |
| **自动化测试** | Tester Agent | 生成测试用例 |
| **Bug 修复** | Debugger Agent | 定位和修复问题 |
| **文档生成** | Documenter Agent | 生成技术文档 |
| **数据分析** | Analyst Agent | 处理数据任务 |
| **运维自动化** | Ops Agent | 自动化运维操作 |

---

## 参考资源

### 论文

- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
- [AutoGen: Enabling Next-Gen LLM Applications](https://arxiv.org/abs/2308.08155)

### 框架文档

- [LangChain Agents](https://python.langchain.com/docs/modules/agents/)
- [AutoGen Documentation](https://microsoft.github.io/autogen/)
- [Claude Code CLI](https://docs.anthropic.com/claude-code)

---

**文档更新时间：2025 年 12 月**

---

## AI 沙箱（Sandbox）

# AI 沙箱（AI Sandbox）

## 概述

**AI 沙箱** 是一个**隔离的执行环境**，用于安全地运行 AI 生成的代码、执行命令或进行实验。沙箱确保 AI 操作不会影响宿主系统，同时提供可控的测试环境。

> **核心价值**：安全性 + 可控性 + 可重复性

---

## 为什么需要 AI 沙箱

### 1. 安全风险

没有沙箱的情况下，AI 可能：

- 删除重要文件
- 执行恶意命令
- 访问敏感数据
- 消耗系统资源
- 感染网络环境

### 2. 典型场景

| 场景 | 风险 | 沙箱解决方案 |
| ---- | ---- | ----------- |
| AI 生成代码执行 | 代码可能包含恶意逻辑 | 在容器中执行 |
| AI 调用系统命令 | 命令可能破坏系统 | 限制可用命令 |
| AI 访问网络 | 可能访问恶意网站 | 网络隔离/代理 |
| AI 修改文件 | 可能删除重要文件 | 文件系统隔离 |

---

## 沙箱的类型

### 1. 进程级沙箱

隔离单个进程：

```
┌─────────────────────────────────────────────────────────┐
│                    进程沙箱                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐         ┌──────────────┐             │
│  │   宿主系统    │         │  沙箱进程    │             │
│  │              │         │              │             │
│  │  ┌────────┐  │  ──▶    │  ┌────────┐  │             │
│  │  │ 其他   │  │         │  │ AI 代码 │  │             │
│  │  │ 进程   │  │         │  │ 执行   │  │             │
│  │  └────────┘  │         │  └────────┘  │             │
│  │              │         │              │             │
│  └──────────────┘         └──────────────┘             │
│         ▲                         ▲                     │
│         └─────────────────────────┘                     │
│              权限隔离（chroot, namespace）              │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

**技术**：
- Linux: chroot, namespace, seccomp
- macOS: sandbox_exec
- Windows: Job Objects, Restricted Tokens

### 2. 容器级沙箱

使用容器技术隔离：

```
┌─────────────────────────────────────────────────────────┐
│                    容器沙箱                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────┐        │
│  │              宿主系统                        │        │
│  │  ┌─────────────────────────────────────┐   │        │
│  │  │          Docker/Podman 容器         │   │        │
│  │  │  ┌─────────────────────────────┐    │   │        │
│  │  │  │       AI 执行环境           │    │   │        │
│  │  │  │  - 独立文件系统             │    │   │        │
│  │  │  │  - 独立网络栈               │    │   │        │
│  │  │  │  - 资源限制                 │    │   │        │
│  │  │  └─────────────────────────────┘    │   │        │
│  │  └─────────────────────────────────────┘   │        │
│  └─────────────────────────────────────────────┘        │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

**技术**：
- Docker
- Podman
- Kubernetes (Pod)
- gVisor (用户空间内核)

### 3. 虚拟机级沙箱

完整的虚拟化隔离：

```
┌─────────────────────────────────────────────────────────┐
│                    虚拟机沙箱                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────┐        │
│  │              宿主操作系统                    │        │
│  │  ┌─────────────────────────────────────┐   │        │
│  │  │         Hypervisor (KVM/VMware)      │   │        │
│  │  │  ┌─────────────────────────────┐    │   │        │
│  │  │  │      虚拟机操作系统           │    │   │        │
│  │  │  │  ┌─────────────────────┐     │    │   │        │
│  │  │  │  │   AI 执行环境       │     │    │   │        │
│  │  │  │  │  - 完整隔离         │     │    │   │        │
│  │  │  │  │  - 独立内核         │     │    │   │        │
│  │  │  │  │  - 硬件虚拟化       │     │    │   │        │
│  │  │  │  └─────────────────────┘     │    │   │        │
│  │  │  └─────────────────────────────┘    │   │        │
│  │  └─────────────────────────────────────┘   │        │
│  └─────────────────────────────────────────────┘        │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

**技术**：
- KVM / QEMU
- VMware
- VirtualBox
- Firecracker (微虚拟机)

### 4. Web 沙箱

在浏览器/服务器端执行 JavaScript：

```
┌─────────────────────────────────────────────────────────┐
│                    Web 沙箱                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────┐        │
│  │              浏览器/服务器                   │        │
│  │  ┌─────────────────────────────────────┐   │        │
│  │  │         iframe / Web Worker         │   │        │
│  │  │  ┌─────────────────────────────┐    │   │        │
│  │  │  │     AI 生成的 JavaScript     │    │   │        │
│  │  │  │  - SOP 限制                 │    │   │        │
│  │  │  │  - CSP 策略                 │    │   │        │
│  │  │  │  - 内存隔离                 │    │   │        │
│  │  │  └─────────────────────────────┘    │   │        │
│  │  └─────────────────────────────────────┘   │        │
│  └─────────────────────────────────────────────┘        │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

**技术**：
- iframe + sandbox 属性
- Web Workers
- Service Workers
- QuickJS (嵌入式 JS 引擎)

---

## 主流 AI 沙箱方案

### 1. E2B

专为 AI 代码执行设计的沙箱：

```bash
# 安装 E2B
pip install e2b

# 使用示例
from e2b import Sandbox

sandbox = Sandbox()
result = sandbox.run_code("print('Hello from AI!')")
```

**特点**：
- 专为 LLM 设计
- 预装常用工具
- 支持多种编程语言
- API 简单易用

### 2. Docker Exec

直接使用 Docker 作为沙箱：

```bash
# 运行容器执行代码
docker run --rm -v $(pwd):/workspace python:3.12 \
  python /workspace/script.py

# 限制资源
docker run --rm \
  --memory="512m" \
  --cpus="1.0" \
  --network=none \
  python:3.12 python script.py
```

### 3. Firecracker

AWS Lambda 使用的微虚拟机：

```json
{
  "boot_source": {
    "kernel_image_path": "vmlinux.bin"
  },
  "drives": [
    {
      "drive_id": "rootfs",
      "path_on_host": "rootfs.ext4",
      "is_root_device": true,
      "is_read_only": false
    }
  ],
  "machine_config": {
    "vcpu_count": 1,
    "mem_size_mib": 512
  }
}
```

### 4. WebAssembly (WASM)

在浏览器中安全执行：

```javascript
// QuickJS WASM 沙箱

const { evalCode } = await getQuickJS();

// 在隔离环境中执行代码
const result = evalCode(`
  const sum = (a, b) => a + b;
  sum(1, 2);
`);
```

---

## AI 工具中的沙箱使用

### Claude Code CLI

Claude Code 使用系统级沙箱：

```typescript
// 安全执行命令
const result = await Bash({
  command: "npm test",
  options: {
    timeout: 30000,
    cwd: workspaceDir,
    env: { ...process.env, NODE_ENV: 'test' }
  }
});
```

**安全措施**：
- 命令超时限制
- 工作目录限制
- 环境变量过滤
- 文件访问权限控制

### Cursor IDE

Cursor 使用容器执行代码：

- 每个 Tab 在独立环境中运行
- 文件系统访问需用户授权
- 网络请求可配置

### GitHub Codespaces

完整的云开发环境作为沙箱：

```
用户代码 → Codespaces 容器 → 隔离执行环境
                      ↓
                  资源限制
                      ↓
                  网络隔离
```

---

## 构建自己的 AI 沙箱

### 基础方案：Python subprocess

```python

def execute_in_sandbox(code: str, timeout: int = 30):
    """在临时目录中执行代码"""
    with tempfile.TemporaryDirectory() as tmpdir:
        # 写入代码文件
        code_file = os.path.join(tmpdir, 'script.py')
        with open(code_file, 'w') as f:
            f.write(code)

        # 执行代码（带超时）
        result = subprocess.run(
            ['python', code_file],
            cwd=tmpdir,
            timeout=timeout,
            capture_output=True,
            text=True
        )

        return result.stdout, result.stderr, result.returncode
```

### 中级方案：Docker

```python

def execute_in_docker(code: str, language: str = 'python'):
    """在 Docker 容器中执行代码"""
    client = docker.from_env()

    # 运行容器
    container = client.containers.run(
        f'{language}:3.12-slim',
        command=['python', '-c', code],
        mem_limit='512m',
        cpu_quota=100000,
        network_disabled=True,
        detach=True
    )

    # 等待执行完成
    result = container.wait()
    logs = container.logs()

    # 清理
    container.remove()

    return logs.decode('utf-8')
```

### 高级方案：gVisor

```bash
# 使用 gVisor 运行容器
docker run --runtime=runsc --rm python:3.12 python -c "print('Hello')"
```

---

## 沙箱的最佳实践

### 1. 资源限制

| 资源 | 建议限制 | 原因 |
| ---- | -------- | ---- |
| CPU | 1-2 核心 | 防止 CPU 占用 |
| 内存 | 512MB-2GB | 防止内存耗尽 |
| 磁盘 | 1GB | 限制存储使用 |
| 网络 | 禁用或代理 | 防止恶意访问 |
| 时间 | 30-60秒 | 防止无限循环 |

### 2. 文件系统隔离

- 使用临时文件系统
- 禁止访问宿主目录
- 提供虚拟文件系统

### 3. 网络隔离

- 默认禁用网络
- 需要时使用白名单
- 记录所有网络请求

### 4. 日志和监控

- 记录所有操作
- 监控资源使用
- 异常行为告警

### 5. 清理机制

- 执行后自动清理
- 定时清理残留
- 资源回收

---

## 沙箱方案对比

| 方案 | 隔离级别 | 性能 | 复杂度 | 适用场景 |
| ---- | -------- | ---- | ------ | -------- |
| **进程级** | 低 | 高 | 低 | 简单脚本 |
| **容器** | 中 | 高 | 中 | 通用场景 |
| **虚拟机** | 高 | 中 | 高 | 高安全要求 |
| **Web WASM** | 中 | 中 | 低 | 浏览器环境 |
| **E2B** | 中 | 高 | 低 | 快速集成 |

---

## 参考资源

### 开源项目

- [E2B](https://github.com/e2b-dev/e2b) - AI 代码执行沙箱
- [gVisor](https://github.com/google/gvisor) - 用户空间内核
- [Firecracker](https://github.com/firecracker-microvm/firecracker) - 微虚拟机
- [QuickJS](https://github.com/quickjs-ng/quickjs) - 轻量级 JS 引擎

### 文档

- [Docker 安全](https://docs.docker.com/engine/security/)
- [Linux Namespace](https://man7.org/linux/man-pages/man7/namespaces.7.html)
- [seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html)

---

**文档更新时间：2025 年 12 月**

---

## 上下文窗口（Context Window）


## 概述

**上下文窗口 (Context Window)** 是大语言模型在单次对话中**能够记忆和处理的最大 Token 数量**。它决定了模型能"看到"和"理解"多少信息。

> **简单理解**：上下文窗口 = 模型的"短期记忆容量"

---

## 核心概念

### 1. 上下文窗口的组成

```
┌─────────────────────────────────────────────────────────┐
│                    上下文窗口                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ 系统提示  │  │对话历史  │  │  用户    │             │
│  │ System   │  │ History  │  │  Query   │             │
│  │ Prompt   │  │          │  │          │             │
│  └──────────┘  └──────────┘  └──────────┘             │
│      │              │              │                   │
│      ▼              ▼              ▼                   │
│  [========|============|============]                  │
│  └───────────────────────────────────────────────────┘  │
│                     总 Token 数 ≤ 上下文窗口             │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 2. 输入 vs 输出窗口

| 类型 | 说明 |
| ---- | ---- |
| **输入窗口** | 模型能接收的最大 Token 数 |
| **输出窗口** | 模型能生成的最大 Token 数（通常 < 输入） |

---

## 主流模型的上下文窗口

### 超长上下文模型 (>500K)

| 模型 | 上下文长度 | 发布时间 |
| ---- | ---------- | -------- |
| **Gemini 2.0 Pro** | 2M tokens | 2025.02 |
| **Gemini 1.5 Pro** | 1M tokens | 2024.02 |
| **GPT-5.2** | 1M tokens | 2024.12 |
| **Claude 3** | 200K tokens | 2024.03 |

### 标准上下文模型 (100K-200K)

| 模型 | 上下文长度 |
| ---- | ---------- |
| **Claude Opus 4.5** | 200K |
| **Claude Sonnet 4.5** | 200K |
| **GPT-4o** | 128K |
| **GLM-4.7** | 128K |

### 中等上下文模型 (32K-100K)

| 模型 | 上下文长度 |
| ---- | ---------- |
| **GPT-4** | 32K / 8K |
| **Claude 2** | 100K |
| **Llama 3.1** | 128K |

### 小上下文模型 (<32K)

| 模型 | 上下文长度 |
| ---- | ---------- |
| **GPT-3.5** | 16K / 4K |
| **原始 Claude** | 9K / 72K |
| **Llama 2** | 4K |

---

## 上下文窗口的演进

```
2020 ────── 2022 ────── 2024 ────── 2026
 │           │           │           │
2048    →   32K    →   128K   →   2M
 (GPT-3)     (GPT-4)     (GPT-4 Turbo)  (Gemini)
```

**关键里程碑**：

| 时间 | 模型 | 窗口大小 | 意义 |
| ---- | ---- | -------- | ---- |
| 2020.06 | GPT-3 | 2K | 首次大规模应用 |
| 2023.03 | GPT-4 | 32K | 长文本处理 |
| 2023.07 | Claude 2 | 100K | 超长上下文 |
| 2024.02 | Gemini 1.5 | 1M | 百万级突破 |
| 2025.02 | Gemini 2.0 | 2M | 当前最大 |

---

## 上下文窗口的作用

### 1. 代码分析

```
项目规模        所需窗口    推荐模型
────────────────────────────────────
单个文件        1K          任意
小型项目        50K-100K    Claude, GPT-4
中型项目        200K-500K   Gemini 1.5
大型项目        1M+         Gemini 2.0 Pro
全库分析        2M+         Gemini 2.0 Pro (需分块)
```

### 2. 文档处理

| 文档类型 | 长度 | 所需模型 |
| -------- | ---- | -------- |
| 短文章 | <5K tokens | 任意 |
| 长文章 | 20-50K tokens | Claude 3, GPT-4 |
| 书籍 | 100-500K tokens | Gemini 1.5, Claude 3 |
| 法律文档 | 500K-1M tokens | Gemini 2.0 Pro |

### 3. 多轮对话

```
对话轮数    平均Token/轮    总Token    需要模型
────────────────────────────────────────
10轮       500             5K         任意
50轮       500             25K        Claude, GPT-4
100轮      500             50K        Claude 3
500轮      500             250K       Gemini 1.5+
```

---

## 上下文管理技术

### 1. 滑动窗口

```
原始上下文: [A][B][C][D][E][F][G][H][I][J]
窗口大小: 4

步骤1: [A][B][C][D]
步骤2:    [B][C][D][E]
步骤3:       [C][D][E][F]
步骤4:          [D][E][F][G]
...
```

### 2. 重要性采样

```
完整上下文: [A][B][C][D][E][F][G][H][I][J]
重要性:      ↑     ↑     ↑     ↑
保留:        [A][C][E][G][I]
```

### 3. 分块处理

```
大文档: [==== ==== ==== ==== ==== ====]
                      ↓
分块:   [块1][块2][块3][块4][块5][块6]
                      ↓
汇总:   [摘要1][摘要2][摘要3][摘要4][摘要5][摘要6]
                      ↓
最终:   [综合摘要]
```

### 4. 向量检索 (RAG)

```
用户问题 → 向量化 → 检索相关片段 → 添加到上下文
                            ↓
                    [系统提示] + [检索片段] + [用户问题]
                            ↓
                        模型回答
```

---

## 超长上下文技术

### 1. 注意力机制优化

**核心问题**：传统注意力的复杂度是 O(n²)

| 技术 | 复杂度 | 说明 |
| ---- | ------ | ---- |
| **Flash Attention** | O(n²) | 优化内存访问 |
| **Ring Attention** | O(n²) | 块级计算 |
| **Linear Attention** | O(n) | 线性近似 |

### 2. 位置编码

| 技术 | 最大长度 | 说明 |
| ---- | -------- | ---- |
| **绝对位置编码** | 2048 | GPT-3 使用 |
| **相对位置编码** | 8192 | T5 使用 |
| **RoPE (旋转位置)** | ∞ | LLaMA, Gemini 使用 |
| **ALiBi** | ∞ | BLOOM 使用 |

### 3. KV Cache 压缩

```
原始 KV Cache: [==== ==== ==== ==== ====] (占用大量内存)
压缩后:          [==  ==  ==  ==  ==]  (保留关键信息)
```

---

## 上下文窗口的最佳实践

### 1. 选择合适的模型

| 场景 | 推荐模型 | 窗口大小 |
| ---- | -------- | -------- |
| 简单对话 | GPT-4o-mini, Claude Haiku | 128K |
| 代码审查 | Claude Opus 4.5 | 200K |
| 全库分析 | Gemini 2.0 Pro | 2M |
| 文档问答 | Gemini 1.5 Pro | 1M |

### 2. 优化上下文使用

```diff
- 包含整个文件历史
+ 只包含当前修改的部分

- 重复发送相同信息
+ 使用引用或缓存

- 冗长的系统提示
+ 精简有效的提示词
```

### 3. 监控 Token 使用

```python

client = anthropic.Anthropic()

# 检查 Token 使用
response = client.messages.count_tokens(
    model="claude-3-opus-20240229",
    text="你的内容..."
)

print(f"输入 Token: {response.input_tokens}")
print(f"窗口使用率: {response.input_tokens / 200000 * 100:.1f}%")
```

---

## 上下文窗口的局限性

### 1. 质量下降

当上下文接近窗口上限时，模型可能：

- 遗忘早期信息
- 回答质量下降
- 出现幻觉

### 2. 成本增加

```
Token 数量 ∝ API 成本
```

### 3. 延迟增加

```
上下文长度 → 推理时间
10K tokens  → ~2秒
100K tokens → ~10秒
1M tokens   → ~60秒+
```

---

## 参考资源

### 论文

- [Transformer-XL](https://arxiv.org/abs/1901.02860) - 超长上下文 Transformer
- [Ring Attention](https://arxiv.org/abs/2310.01889) - 块级注意力
- [MegaByte](https://arxiv.org/abs/2310.05414) - 百万级上下文

### 技术博客

- [Anthropic Context Window](https://www.anthropic.com/index/context-window)
- [Google Gemini 1.5](https://blog.google/technology/ai/google-gemini-next-generation-model-february-2025/)

---

**文档更新时间：2025 年 12 月**

---

## LLMs.txt（LLM 友好文档）


## 概述

**llms.txt** 是一个项目根目录下的文本文件，用于为**大语言模型（LLM）提供项目上下文**。它类似于 `README.md`，但专门为 AI 工具（如 Claude Code、Cursor、Cline）设计，帮助 AI 更好地理解和操作代码库。

> **核心价值**：让 AI 快速理解项目结构、编码规范、技术栈，提供更精准的帮助

---

## llms.txt 的作用

### 1. 为 AI 提供项目上下文

```
传统方式:
AI: "这个项目是做什么的?"
用户: "这是一个小程序项目..."
AI: "使用什么框架?"
用户: "使用原生小程序..."
AI: "有什么编码规范?"
用户: "......"

有了 llms.txt:
AI 直接读取 llms.txt → 自动了解项目信息 → 精准提供帮助
```

### 2. 与 Claude Code CLAUDE.md 的关系

| 文件 | 目标用户 | 内容侧重 |
| ---- | -------- | -------- |
| **llms.txt** | 通用 LLM | 项目概述、技术栈、快速开始 |
| **CLAUDE.md** | Claude Code 专属 | 详细的工作流、命令、最佳实践 |

### 3. 标准 vs 自定义

```
llms.txt (标准)
├── 通用格式
├── 所有 LLM 都能理解
└── 社区标准

自定义命名
├── .cursorrules (Cursor 专属)
├── .clinerules (Cline 专属)
└── project_context.md (自定义)
```

---

## llms.txt 的标准格式

### 推荐结构

```markdown
# 项目名称

## 项目概述
一句话描述项目

## 技术栈
- 框架: ...
- 语言: ...
- 工具: ...

## 项目结构
简短的目录说明

## 快速开始
如何运行项目

## 编码规范
代码风格要求

## 重要说明
其他需要注意的事项
```

---

## llms.txt 模板

### 完整模板

```markdown
# [项目名称]

## 项目概述
[一句话描述项目是做什么的]

## 技术栈
- **框架**: [使用的主要框架]
- **语言**: [主要编程语言]
- **构建工具**: [如 webpack, vite, gulp]
- **测试框架**: [如 vitest, jest]
- **其他工具**: [其他重要依赖]

## 项目结构
```
src/
├── components/    # 组件目录
├── utils/         # 工具函数
├── pages/         # 页面
└── styles/        # 样式文件
```

## 快速开始

### 安装依赖
```bash
pnpm install
```

### 开发模式
```bash
pnpm dev
```

### 构建
```bash
pnpm build
```

### 测试
```bash
pnpm test
```

## 编码规范
- 使用 TypeScript 严格模式
- 组件使用函数式声明
- 文件命名使用 kebab-case
- 遵循 ESLint 规则

## 重要说明
- [特殊约定]
- [注意事项]
- [已知问题]
```

### 小程序项目模板

```markdown
# 小程序项目名称

## 项目概述
一个基于原生小程序框架的 [功能描述] 应用

## 技术栈
- **框架**: 原生小程序 (微信/支付宝/抖音)
- **构建**: gulp + weapp-tailwindcss
- **样式**: TailwindCSS (原子化 CSS)
- **语言**: JavaScript / TypeScript

## 项目结构
```
pages/           # 页面目录
├── index/       # 首页
├── profile/     # 个人中心
components/      # 组件目录
utils/           # 工具函数
styles/          # 全局样式
assets/          # 静态资源
```

## 快速开始
```bash
# 安装依赖
pnpm install

# 开发模式 (微信小程序)
pnpm dev:wechat

# 构建
pnpm build
```

## 编码规范
- 组件命名使用 kebab-case
- 页面命名使用 kebab-case
- 样式使用 TailwindCSS 原子类
- 避免使用 id 选择器

## 重要说明
- 使用 weapp-tailwindcss 进行 CSS 转换
- 图片资源需放在 assets/ 目录
- 遵循小程序开发规范
```

### React 项目模板

```markdown
# React 项目名称

## 项目概述
使用 React + TypeScript 构建的 [项目描述]

## 技术栈
- **框架**: React 18+
- **语言**: TypeScript
- **构建**: Vite
- **状态管理**: Zustand / Redux
- **路由**: React Router
- **UI**: TailwindCSS + shadcn/ui

## 项目结构
```
src/
├── components/    # 通用组件
├── pages/         # 页面组件
├── hooks/         # 自定义 Hooks
├── store/         # 状态管理
├── services/      # API 服务
├── types/         # TypeScript 类型
└── utils/         # 工具函数
```

## 快速开始
```bash
pnpm install
pnpm dev
```

## 编码规范
- 组件使用函数式声明 + hooks
- 使用 TypeScript 类型
- 遵循 ESLint + Prettier 规则
```

---

## AI 工具对 llms.txt 的支持

### 1. Claude Code

Claude Code 会**自动读取**项目根目录的 `llms.txt`：

```
项目根目录/
├── llms.txt          ← AI 自动读取
├── CLAUDE.md         ← Claude Code 专属配置
├── package.json
└── src/
```

### 2. Cursor

Cursor 支持 `llms.txt`，同时也支持 `.cursorrules`：

```diff
+ llms.txt          # 通用 LLM 上下文
+ .cursorrules      # Cursor 特定规则
```

### 3. Cline

Cline（VS Code 插件）读取 `.clinerules` 或 `llms.txt`：

```
项目根目录/
├── .clinerules       ← Cline 配置
├── llms.txt         ← 备用
└── src/
```

### 4. 其他工具

| 工具 | 支持的文件 |
| ---- | ---------- |
| **Roo Code** | `roo-rules.txt` |
| **Continue** | `continue_config.json` |
| **Aider** | `.aider.conf.yml` |

---

## llms.txt 最佳实践

### 1. 保持简洁

```markdown
# ❌ 太详细
本项目是一个复杂的企业级应用，包含......（长篇大论）

# ✅ 简洁明确
电商小程序，包含商品展示、购物车、支付功能
```

### 2. 结构化信息

```markdown
# ✅ 使用列表和代码块

## 技术栈
- React 18
- TypeScript
- TailwindCSS

## 命令
```bash
pnpm dev    # 开发
pnpm build  # 构建
```
```

### 3. 突出重点

```markdown
## 重要约定
1. 所有 API 请求必须经过 services/api.ts
2. 组件必须使用 TypeScript 定义 props
3. 样式只能使用 TailwindCSS 原子类
```

### 4. 保持更新

```markdown
## 最后更新
2025-12-26

## 最近变更
- 迁移到 Vite 6
- 添加 PWA 支持
```

---

## llms.txt 示例

### 示例 1：小程序项目

```markdown
# 小程序商城

## 项目概述
微信小程序商城，支持商品浏览、购物车、微信支付

## 技术栈
- 原生小程序框架
- weapp-tailwindcss (TailwindCSS)
- gulp 构建工具

## 项目结构
```
pages/
├── home/          # 首页
├── category/      # 分类
├── product/       # 商品详情
├── cart/          # 购物车
└── order/         # 订单
components/
├── product-card/  # 商品卡片
├── address-picker/# 地址选择
utils/
├── request.js     # API 封装
└── auth.js        # 登录认证
```

## 快速开始
```bash
pnpm install
pnpm dev:wechat
```

## 编码规范
- 组件命名: kebab-case
- 样式: TailwindCSS 原子类
- 不使用 id 选择器
- 图片路径使用绝对路径

## API 配置
- 基础 URL: `https://api.example.com`
- 需要登录的接口自动带上 token

## 重要说明
- 使用微信登录获取用户信息
- 支付使用微信支付 API
```

### 示例 2：全栈项目

```markdown
# 全栈任务管理系统

## 项目概述
全栈任务管理应用，包含前端、后端和数据库

## 技术栈

### 前端
- React 18 + TypeScript
- Vite
- TailwindCSS + shadcn/ui
- React Query (TanStack Query)

### 后端
- Node.js + Express
- TypeScript
- Prisma ORM
- PostgreSQL

## 项目结构
```
frontend/           # React 前端
├── src/
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   └── services/
backend/            # Node.js 后端
├── src/
│   ├── routes/
│   ├── services/
│   ├── models/
│   └── middleware/
```

## 快速开始
```bash
# 前端
cd frontend && pnpm dev

# 后端
cd backend && pnpm dev

# 数据库
docker-compose up -d postgres
```

## 编码规范
- 前后端都使用 TypeScript
- API 遵循 RESTful 规范
- 组件使用函数式声明
- 使用 ESLint + Prettier

## 环境变量
```
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret
API_URL=http://localhost:3001
```
```

---

## llms.txt 与 CLAUDE.md 的配合

### 推荐的配置结构

```
项目根目录/
├── llms.txt              # AI 通用上下文（所有 LLM）
├── CLAUDE.md             # Claude Code 专属配置
├── .cursorrules          # Cursor 专属规则（可选）
└── .clinerules           # Cline 专属规则（可选）
```

### 内容分工

| 文件 | 内容 |
| ---- | ---- |
| **llms.txt** | 项目概述、技术栈、结构、快速开始 |
| **CLAUDE.md** | Claude 专属工作流、命令、插件配置 |

### llms.txt 示例

```markdown
# 项目名称

## 项目概述
一个 React + Node.js 的全栈应用

## 技术栈
- React 18 + TypeScript
- Node.js + Express
- PostgreSQL

## 快速开始
pnpm install
pnpm dev
```

### CLAUDE.md 示例

```markdown
# Claude Code 配置

## 项目上下文
本项目使用 React + Node.js 全栈架构

## 工作流
1. 新功能先在 frontend/src/ 中创建组件
2. API 变更在 backend/src/routes/ 中修改
3. 运行 pnpm test 验证

## 常用命令
- pnpm dev: 启动开发服务器
- pnpm test: 运行测试
- pnpm lint: 代码检查

## 注意事项
- 前端组件必须使用 TypeScript
- API 路由需要添加认证中间件
```

---

## 参考

### 官方资源

- [llmstxt.org](https://llmstxt.org) - llms.txt 官方网站
- [llms.txt 规范](https://github.com/pydantic/llms.txt)

### 相关文档

- [CLAUDE.md 最佳实践](https://docs.anthropic.com/claude-code/project-knowledge)
- [Cursor Rules](https://cursor.com/docs/rules)

---

**文档更新时间：2025 年 12 月**

---

## MCP (Model Context Protocol)


## 概述

**MCP (Model Context Protocol)** 是一个开放协议，用于连接 AI 助手与系统上下文（数据源、工具、环境）。它由 Anthropic 于 2024 年 11 月发布，旨在解决 AI 应用与外部系统集成的标准化问题。

> **官方文档**：[https://modelcontextprotocol.io](https://modelcontextprotocol.io)
> **GitHub**：[https://github.com/modelcontextprotocol](https://github.com/modelcontextprotocol)

---

## 核心概念

### 1. MCP 的定义

MCP 是一种**客户端-服务端协议**，定义了：

- AI 应用（客户端）如何请求数据和操作
- 数据源/工具（服务端）如何暴露其能力
- 消息传输的标准格式

### 2. 架构组件

```
┌─────────────────────────────────────────────────────────┐
│                    MCP 架构                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐         ┌──────────────┐            │
│  │   MCP Client │ ───────▶│  MCP Server  │            │
│  │   (AI 应用)   │  ◀──────│  (数据源)    │            │
│  └──────────────┘         └──────────────┘            │
│         │                         │                     │
│         ▼                         ▼                     │
│  ┌──────────────┐         ┌──────────────┐            │
│  │ Claude Code  │         │ 文件系统     │            │
│  │ Cursor IDE   │         │ 数据库       │            │
│  │ Cline        │         │ API 服务     │            │
│  │ 自定义应用    │         │ Git 仓库     │            │
│  └──────────────┘         └──────────────┘            │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## MCP 的核心能力

### 1. 资源 (Resources)

**资源**是服务端暴露给客户端的**数据读取接口**。

```typescript
// 资源示例
{
  "uri": "file:///Users/project/README.md",
  "name": "项目 README",
  "description": "项目根目录的 README 文件",
  "mimeType": "text/markdown"
}
```

**常见资源类型**：

| 类型 | URI 示例 | 说明 |
| ---- | -------- | ---- |
| 文件 | `file:///path/to/file` | 本地文件系统 |
| Git | `git:///repo/file` | Git 仓库内容 |
| 数据库 | `postgres://query` | 数据库查询结果 |
| API | `https://api/data` | HTTP API 响应 |
| 内存 | `memory://variable` | 运行时数据 |

### 2. 提示词模板 (Prompts)

**提示词模板**是服务端提供的**预定义提示词**。

```typescript
// 提示词模板示例
{
  "name": "code-review",
  "description": "代码审查提示词",
  "arguments": {
    "file": "要审查的文件路径",
    "focus": "审查重点（安全/性能/风格）"
  }
}
```

### 3. 工具 (Tools)

**工具**是服务端暴露的**可执行功能**。

```typescript
// 工具示例
{
  "name": "execute_command",
  "description": "在终端执行命令",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "description": "要执行的命令"
      }
    }
  }
}
```

---

## MCP 传输层

MCP 支持多种传输方式：

### 1. STDIO（标准输入/输出）

适用于**本地进程间通信**：

```bash
# 通过 STDIO 启动 MCP 服务端
claude-code mcp install my-server
my-server --stdio
```

### 2. SSE（Server-Sent Events）

适用于**本地 HTTP 通信**：

```typescript
// SSE 连接
const client = new MCPClient({
  url: "http://localhost:3000/sse",
  transport: "sse"
});
```

### 3. 自定义传输

支持自定义 WebSocket、gRPC 等传输层。

---

## 使用场景

### 1. Claude Code 中的 MCP

Claude Code 原生支持 MCP，可以：

- 通过 MCP 读取项目文件
- 通过 MCP 执行 Git 命令
- 通过 MCP 访问数据库
- 通过 MCP 调用外部 API

**配置示例**：

```json
// .claude/mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

### 2. Cursor IDE 中的 MCP

Cursor 支持 MCP 扩展：

- 安装 MCP 兼容的服务端
- Cursor 自动发现可用资源
- 在 Chat 中引用 MCP 资源

### 3. Cline 中的 MCP

Cline（VS Code 插件）支持 MCP：

- 通过 MCP 获取项目上下文
- 通过 MCP 执行构建命令
- 通过 MCP 访问测试结果

---

## MCP 服务端示例

### 文件系统服务端

```bash
# 官方文件系统服务端
npx -y @modelcontextprotocol/server-filesystem /path/to/directory
```

### GitHub 服务端

```bash
# 官方 GitHub 服务端
npx -y @modelcontextprotocol/server-github
```

### 数据库服务端

```bash
# PostgreSQL 服务端
npx -y @modelcontextprotocol/server-postgres "postgresql://..."
```

### 自定义服务端

```typescript
// 自定义 MCP 服务端

const server = new Server({
  name: 'my-custom-server',
  version: '1.0.0'
});

// 添加资源
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [
    {
      uri: 'custom://data',
      name: '自定义数据',
      description: '我的自定义数据源'
    }
  ]
}));

// 启动服务端
const transport = new StdioServerTransport();
await server.connect(transport);
```

---

## MCP 的优势

| 优势 | 说明 |
| ---- | ---- |
| **标准化** | 统一的协议，无需为每个 AI 应用单独适配 |
| **模块化** | 数据源独立于 AI 应用，可复用 |
| **可扩展** | 支持自定义传输层和数据源 |
| **安全性** | 明确的权限控制和数据隔离 |
| **开放性** | 开源协议，社区驱动发展 |

---

## MCP 与其他方案的对比

| 方案 | MCP | LangChain Tools | OpenAI Function Calling |
| ---- | --- | --------------- | ---------------------- |
| **标准化程度** | ✅ 开放协议 | ❌ 厂商特定 | ❌ 厂商特定 |
| **传输层** | 多种支持 | HTTP/RPC | HTTP |
| **AI 兼容性** | 多模型 | 主流 LLM | OpenAI only |
| **社区生态** | 快速增长 | 成熟 | 成熟 |
| **学习曲线** | 简单 | 中等 | 简单 |

---

## 快速开始

### 1. 安装 Claude Code MCP 集成

```bash
# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 初始化 MCP 配置
claude-code mcp init
```

### 2. 添加 MCP 服务端

```bash
# 添加文件系统服务端
claude-code mcp install @modelcontextprotocol/server-filesystem

# 添加 GitHub 服务端
claude-code mcp install @modelcontextprotocol/server-github
```

### 3. 在 Claude Code 中使用

```
@mcp://filesystem/Users/project/src 请分析这个目录下的代码结构
```

---

## 参考资源

### 官方资源

- [MCP 官方网站](https://modelcontextprotocol.io)
- [MCP GitHub](https://github.com/modelcontextprotocol)
- [MCP SDK 文档](https://modelcontextprotocol.io/sdk)

### 社区资源

- [MCP 服务端列表](https://github.com/modelcontextprotocol/servers)
- [MCP 客户端列表](https://github.com/modelcontextprotocol/clients)
- [Claude Code MCP 文档](https://docs.anthropic.com/claude-code/mcp)

---

**文档更新时间：2025 年 12 月**

---

## Power（规范驱动编程）

# Power（规范驱动编程能力）

## 概述

**Power** 是由 **Kiro** 提出的一个概念，用于衡量 **AI 工具理解复杂规范并生成符合规范代码的能力**。在 Spec-Driven Development（规范驱动开发）的语境下，Power 指的是 AI 将非结构化的需求描述转换为结构化的技术规范，并最终生成可执行代码的能力。

> **核心理念**：Power = 规范理解能力 × 代码生成能力 × 约束遵循能力

---

## Power 的定义

### 1. 基本概念

**Power** 是 AI 编程工具的核心能力指标：

```
┌─────────────────────────────────────────────────────────┐
│                    Power 的构成                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────────────────────────────────────┐      │
│  │         规范理解 (Spec Understanding)          │      │
│  │         理解自然语言需求 → 结构化规范          │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │         规范生成 (Spec Generation)             │      │
│  │         生成 API、数据模型、UI 规范             │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │         代码实现 (Code Implementation)         │      │
│  │         根据规范生成符合要求的代码              │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │         约束遵循 (Constraint Adherence)       │      │
│  │         遵循编码规范、技术约束、业务规则        │      │
│  └──────────────────────────────────────────────┘      │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 2. Power 的维度

| 维度 | 说明 | 评估标准 |
| ---- | ---- | -------- |
| **理解力** | 理解复杂需求的能力 | 能否准确提取关键信息 |
| **结构化** | 生成结构化规范的能力 | 规范是否完整、一致 |
| **实现力** | 生成可执行代码的能力 | 代码是否可用、正确 |
| **遵循力** | 遵循约束的能力 | 是否符合规范要求 |
| **一致性** | 多次输出的稳定性 | 相同输入是否得到相似结果 |

---

## Power 的级别

### Level 0: 无规范能力

```
特征:
- 无法理解结构化需求
- 只能处理简单指令
- 生成代码需要大量人工修改

示例:
输入: "写个登录"
输出: [基础代码，但缺类型、验证、错误处理]
```

### Level 1: 基础规范理解

```
特征:
- 能理解简单的结构化需求
- 能生成基本的代码框架
- 需要人工补充细节

示例:
输入: "用 React + TypeScript 写登录，包含邮箱和密码"
输出: [带类型的组件，但可能缺验证逻辑]
```

### Level 2: 中级规范能力

```
特征:
- 能理解多层级规范
- 能生成完整的 API 规范
- 代码基本可用，需少量调整

示例:
输入: "用户登录功能，需验证、错误处理、JWT"
输出: [完整的登录流程，含前后端]
```

### Level 3: 高级规范能力

```
特征:
- 能理解复杂的业务规范
- 能生成前后端联调代码
- 包含测试和文档

示例:
输入: "完整的用户认证系统（注册、登录、登出、权限）"
输出: [全栈代码 + API 文档 + 测试用例]
```

### Level 4: 专家级规范能力

```
特征:
- 能理解企业级规范
- 自动处理边界情况和异常
- 生成生产级代码

示例:
输入: "电商订单系统（含支付、库存、物流、退款）"
输出: [微服务架构 + 数据库设计 + 完整实现]
```

---

## Power 的评估

### 1. 评估维度

```markdown
## Power 评估卡

### 需求理解
- [ ] 能识别核心功能
- [ ] 能识别非功能需求（性能、安全）
- [ ] 能识别依赖和约束
- [ ] 能识别边界条件

### 规范生成
- [ ] API 规范完整性
- [ ] 数据模型合理性
- [ ] 错误处理覆盖
- [ ] 验证规则完整

### 代码质量
- [ ] 语法正确性
- [ ] 类型安全性
- [ ] 代码可读性
- [ ] 最佳实践遵循

### 约束遵循
- [ ] 技术栈约束
- [ ] 编码规范约束
- [ ] 业务规则约束
- [ ] 性能约束
```

### 2. 评分标准

| 分数 | 描述 |
| ---- | ---- |
| **0-20** | 几乎无法理解规范 |
| **20-40** | 能理解简单规范，代码需大量修改 |
| **40-60** | 能理解中等规范，代码需少量修改 |
| **60-80** | 能理解复杂规范，代码基本可用 |
| **80-100** | 完全理解规范，生成生产级代码 |

### 3. 自动化评估

```python
# Power 评估脚本示例
def evaluate_power(ai_tool, test_cases):
    scores = []
    for case in test_cases:
        # 生成规范
        spec = ai_tool.generate_spec(case.requirement)

        # 生成代码
        code = ai_tool.generate_code(spec)

        # 评估
        score = {
            "spec_completeness": check_spec_completeness(spec, case),
            "code_correctness": check_code_correctness(code),
            "constraint_adherence": check_constraints(code, case.constraints),
            "test_pass_rate": run_tests(code, case.tests)
        }

        scores.append(score)

    return aggregate_scores(scores)
```

---

## Power 在不同工具中的体现

### 1. Cursor Composer

Cursor 的 **Composer** 特性：

```
特点:
├── 自动规划任务步骤
├── 跨文件代码生成
├── 上下文感知
└── 迭代优化

Power 水平: Level 2-3
```

### 2. Claude Code

Claude Code 的 **Plan Mode**：

```
特点:
├── 深度代码理解
├── 分步实施计划
├── 人工确认机制
└── 详细说明

Power 水平: Level 3
```

### 3. GitHub Copilot Workspace

Copilot 的 **Workspace**：

```
特点:
├── Issue → Spec → Code 流程
├── 测试生成
├── Pull Request 描述
└── 迭代改进

Power 水平: Level 2-3
```

---

## 提升 Power 的技巧

### 1. 编写更好的规范

#### 使用结构化格式

```markdown
# ❌ 模糊的规范
"做一个用户管理功能"

# ✅ 结构化的规范
## 功能：用户管理

### 需求
- 用户列表（分页、搜索）
- 用户详情
- 创建用户
- 编辑用户
- 删除用户（软删除）

### 字段定义
- id: UUID
- name: 字符串，2-50字符
- email: 邮箱格式，唯一
- role: 枚举（admin, user, guest）
- status: 枚举（active, inactive）
- created_at: 时间戳

### 验证规则
- name 必填
- email 唯一
- role 默认为 user

### API 设计
GET    /api/users      # 列表
GET    /api/users/:id  # 详情
POST   /api/users      # 创建
PUT    /api/users/:id  # 更新
DELETE /api/users/:id  # 删除

### 技术要求
- React + TypeScript
- RESTful API
- 使用 Prisma ORM
```

### 2. 使用模板

```markdown
# 功能规范模板

## 功能概述
[一句话描述]

## 用户故事
作为 [角色]，我想要 [功能]，以便 [目的]

## 验收标准
- [ ] 标准1
- [ ] 标准2

## 技术规范
### 数据模型
### API 接口
### UI 规范

## 非功能需求
### 性能
### 安全
### 兼容性
```

### 3. 渐进式规范

```
第一版（粗略）:
"用户登录功能"

第二版（添加细节）:
"用户登录，邮箱和密码，需要验证"

第三版（完整规范）:
[完整的功能规范，含所有细节]

第四版（迭代优化）:
[基于反馈的优化版本]
```

### 4. 提供示例

```
# 在规范中添加示例

## 输入示例
{
  "email": "user@example.com",
  "password": "SecurePass123"
}

## 输出示例
成功（200）:
{
  "success": true,
  "token": "eyJhbGc...",
  "user": {...}
}

失败（401）:
{
  "success": false,
  "error": "Invalid credentials"
}
```

---

## Power 的局限

### 1. 复杂业务逻辑

```
问题: AI 难以理解复杂的业务规则

解决:
- 分解为多个小功能
- 提供详细规则说明
- 添加决策树/流程图
```

### 2. 隐性知识

```
问题: AI 无法获取团队隐性知识

解决:
- 使用 llms.txt/CLAUDE.md
- 维护项目规范文档
- 建立代码示例库
```

### 3. 上下文限制

```
问题: 大型项目规范超出上下文窗口

解决:
- 分模块编写规范
- 使用 RAG 检索相关规范
- 建立规范层次结构
```

---

## Power 与 Spec-Driven Development

### 关系

```
┌─────────────────────────────────────────────────────────┐
│          Power 在 SDD 中的作用                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Spec-Driven Development 流程:                          │
│                                                         │
│  1. 需求 → 规范                        │
│     └── Power 决定转换质量                              │
│                                                         │
│  2. 规范 → 代码 (Spec → Code)                          │
│     └── Power 决定代码质量                              │
│                                                         │
│  3. 代码 → 测试 (Code → Test)                          │
│     └── Power 影响测试覆盖                              │
│                                                         │
│  结论: Power 越高，SDD 效率越高                          │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 最佳实践

1. **高 Power 工具 + 完整规范** = 最佳效果
2. **低 Power 工具 + 简单规范** = 基础自动化
3. **高 Power 工具 + 简单规范** = 过度设计
4. **低 Power 工具 + 复杂规范** = 效果有限

---

## Power 的发展趋势

### 当前状态 (2025)

```
Level 1-2: 主流
- 大多数 AI 编码工具处于这个水平
- 适合简单到中等复杂度任务

Level 3: 先进
- 少数工具达到
- 需要良好的规范编写

Level 4: 探索
- 研究阶段
- 需要更强的模型和更好的工具支持
```

### 未来方向

```
┌─────────────────────────────────────────────────────────┐
│                    Power 的未来                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  短期（1-2年）                                           │
│  ├── 更好的规范理解                                      │
│  ├── 更准确的代码生成                                    │
│  └── 更强的约束遵循                                      │
│                                                         │
│  中期（2-3年）                                           │
│  ├── 自动化规范生成                                      │
│  ├── 规范版本管理                                        │
│  └── 团队协作支持                                        │
│                                                         │
│  长期（3-5年）                                           │
│  ├── 自演进规范                                          │
│  ├── 跨项目规范复用                                      │
│  └── 规范市场/交换                                       │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## 参考资源

### 相关文档

- [Spec-Driven Development](./spec-driven-development)
- [Vibe Coding](./vibe-coding)
- [Prompt Engineering](./prompt-engineering)

### 工具

- [Cursor](https://cursor.sh) - Composer 功能
- [Claude Code](https://claude.ai/code) - Plan Mode

---

**文档更新时间：2025 年 12 月**

---

## Prompt Engineering（提示词工程）


## 概述

**Prompt（提示词）** 是用户输入给大语言模型的**指令或问题**。**Prompt Engineering（提示词工程）** 是设计和优化提示词以获得更好输出结果的技术。

> **核心原则**：好的提示词 = 清晰、具体、有结构

---

## 什么是提示词

### 1. 基本定义

**提示词** 是与 AI 交互的文本输入：

```
用户输入: "帮我写一个快速排序算法"
          ↑
       这就是 Prompt
```

### 2. 提示词的组成部分

```
┌─────────────────────────────────────────────────────────┐
│                    提示词结构                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────────────────────────────────────┐      │
│  │              角色/身份设定                  │      │
│  │  "你是一个资深前端工程师..."               │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │              任务描述                        │      │
│  │  "帮我实现一个登录表单..."                 │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │              上下文/背景信息                  │      │
│  │  "使用 React + TypeScript..."               │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │              约束/要求                        │      │
│  │  "使用 shadcn/ui 组件，遵循以下规范..."      │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │              输出格式                        │      │
│  │  "以 Markdown 格式输出，包含代码块..."     │      │
│  └──────────────────────────────────────────────┘      │
│                         ↓                               │
│  ┌──────────────────────────────────────────────┐      │
│  │              示例/参考                        │      │
│  │  "参考以下代码风格..."                     │      │
│  └──────────────────────────────────────────────┘      │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## 好的提示词原则

### CREATE 框架

| 原则 | 说明 | 示例 |
| ---- | ---- | ---- |
| **C**lear | 清晰明确 | "用 Python 写一个冒泡排序" |
| **R**ole | 设定角色 | "你是一个资深前端工程师" |
| **E**xact | 精确具体 | "生成 10 个随机整数，范围 1-100" |
| **A**udience | 明确受众 | "向初学者解释闭包的概念" |
| **T**one | 设定语气 | "用专业但友好的语气" |
| **E**xample | 提供示例 | "参考以下代码风格" |

---

## 好的提示词 vs 差的提示词

### 示例 1：代码生成

#### ❌ 差的提示词

```
写一个登录功能
```

**问题**：
- 没有指定技术栈
- 没有说明需求细节
- 没有定义输入输出

#### ✅ 好的提示词

```
你是一个资深前端工程师。请帮我创建一个 React + TypeScript 的登录表单组件：

需求：
1. 包含邮箱和密码输入框
2. 使用 shadcn/ui 组件库
3. 支持表单验证（邮箱格式、密码最少8位）
4. 包含"记住我"复选框
5. 登录按钮在加载时显示 Loading 状态
6. 使用 TypeScript 定义类型

请提供完整的组件代码和类型定义。
```

---

### 示例 2：Bug 修复

#### ❌ 差的提示词

```
这段代码有问题，帮我看看
```

**问题**：
- 没有说明具体问题
- 没有提供错误信息
- 没有说明期望行为

#### ✅ 好的提示词

```
我的 React 组件有问题，需要你帮忙排查：

问题描述：
点击"提交"按钮后，表单没有提交，也没有任何提示

代码：
```tsx
function SubmitForm() {
  const handleSubmit = () => {
    console.log('Form submitted')
  }

  return <button onClick={handleSubmit}>提交</button>
}
```

期望行为：
点击按钮后应该显示"提交成功"的提示

请分析问题并给出修复后的代码。
```

---

### 示例 3：代码重构

#### ❌ 差的提示词

```
优化这段代码
```

**问题**：
- 没有说明优化目标
- 没有说明约束条件
- 没有说明优先级

#### ✅ 好的提示词

```
请帮我优化以下代码，目标是提升可读性和性能：

代码：
```typescript
const getUserData = async (id: string) => {
  const user = await fetchUser(id)
  const posts = await fetchPosts(user.id)
  const comments = await fetchComments(posts.map(p => p.id))
  return { user, posts, comments }
}
```

优化要求：
1. 减少不必要的等待（并行处理）
2. 添加错误处理
3. 添加 TypeScript 类型
4. 保持函数命名清晰

请提供优化后的代码和改动说明。
```

---

### 示例 4：文档编写

#### ❌ 差的提示词

```
帮我写个文档
```

#### ✅ 好的提示词

```
请为以下函数编写 API 文档：

函数：
```typescript
async function createUser(data: {
  email: string
  password: string
  name: string
}): Promise<{id: string; email: string}>
```

文档格式：
- 函数描述
- 参数说明（类型、是否必填）
- 返回值说明
- 使用示例
- 可能抛出的错误

使用 Markdown 格式输出。
```

---

### 示例 5：代码审查

#### ❌ 差的提示词

```
审查这段代码
```

#### ✅ 好的提示词

```
请作为代码审查专家，审查以下 React 组件：

审查重点：
1. 类型安全性
2. 性能问题（不必要的重渲染）
3. 错误处理
4. 代码可读性
5. 最佳实践遵循情况

代码：
```tsx

export function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState(null)
  const [posts, setPosts] = useState([])

  useEffect(() => {
    fetchUser(userId).then(setUser)
    fetchUserPosts(userId).then(setPosts)
  }, [userId])

  if (!user) return Loading...

  return (
    
      {user.name}
      {posts.map(p => {p.title})}
    
  )
}
```

请以列表形式输出：
- 发现的问题
- 严重程度（高/中/低）
- 修复建议
```

---

## 高级提示词技巧

### 1. Few-Shot Prompting（少样本提示）

提供示例帮助 AI 理解期望：

```
请将以下自然语言转换为 SQL 查询语句。

示例1：
输入：查找所有姓张的用户
输出：SELECT * FROM users WHERE name LIKE '张%'

示例2：
输入：查找年龄大于25的用户
输出：SELECT * FROM users WHERE age > 25

示例3：
输入：查找今年注册的用户
输出：SELECT * FROM users WHERE YEAR(created_at) = YEAR(CURDATE())

现在请转换：
输入：查找所有状态为"活跃"且注册时间在2024年之后的用户
输出：
```

### 2. Chain of Thought（思维链）

引导 AI 展示推理过程：

```
请使用逐步推理的方式解决以下问题：

问题：如果一个数列的前三项是 2, 6, 18，求第四项。

推理过程：
1. 观察相邻两项的关系
2. 计算比例关系
3. 验证规律
4. 应用规律求解

请按照以上步骤逐步推理并给出答案。
```

### 3. 角色设定

```
你是一个有 10 年经验的前端工程师，擅长 React 和 TypeScript。
你熟悉各种设计模式和最佳实践。
你的回答应该专业、准确，并包含实用的代码示例。
```

### 4. 结构化输出

```
请以以下格式输出：

## 问题描述
[问题简述]

## 根本原因
[根本原因分析]

## 解决方案
### 选项1
[方案描述]
优点：...
缺点：...

### 选项2
[方案描述]
优点：...
缺点：...

## 推荐
[推荐方案及理由]

## 代码示例
```typescript
[代码]
```
```

### 5. 约束和边界

```
请生成一个随机密码生成函数。

约束条件：
- 密码长度：16-32 位（可配置）
- 必须包含：大写字母、小写字母、数字、特殊字符
- 不能包含容易混淆的字符（如 l, 1, O, 0）
- 使用 TypeScript 实现

请不要使用任何外部库。
```

---

## 常见提示词模板

### 代码生成模板

```
你是一个{语言/框架}专家。

请帮我实现以下功能：
{功能描述}

技术要求：
- 框架：{框架名称}
- 语言：{编程语言}
- 样式：{CSS方案}
- 状态管理：{状态方案}

功能需求：
{详细需求列表}

请提供：
1. 完整的代码实现
2. 必要的说明注释
3. 使用示例

代码风格：
{风格要求}
```

### Bug 修复模板

```
我遇到了一个问题，需要你帮忙解决：

**问题描述**
{问题描述}

**错误信息**
```
{错误日志}
```

**相关代码**
```{language}
{代码}
```

**环境信息**
- 框架：{框架和版本}
- 运行环境：{浏览器/Node版本}
- 构建工具：{webpack/vite等}

**已尝试的解决方案**
{尝试过的方案}

请分析问题原因并提供修复方案。
```

### 代码审查模板

```
请审查以下代码：

**审查重点**
{审查重点列表}

**代码**
```{language}
{代码}
```

**上下文**
{相关背景信息}

请输出：
1. 发现的问题
2. 风险评估
3. 改进建议
```

### 重构建议模板

```
请分析以下代码并提供重构建议：

```{language}
{代码}
```

重构目标：
{目标：如提升性能、提高可读性、降低复杂度}

约束条件：
{约束：如保持 API 不变、不引入新依赖}

请提供：
1. 当前代码的问题分析
2. 重构后的代码
3. 改动说明
```

---

## 提示词反模式

### ❌ 需要避免的模式

| 反模式 | 问题 | 改进 |
| ------ | ---- | ---- |
| **模糊指令** | "帮我优化" | "优化性能，减少 50% 响应时间" |
| **过多信息** | 冗长的背景描述 | 提取关键信息 |
| **矛盾要求** | "简单但功能全" | 明确优先级 |
| **缺少上下文** | "这个函数怎么改" | 提供完整代码和目的 |
| **假设过多** | "你应该知道..." | 明确说明所有信息 |

### ✅ 良好模式

| 模式 | 说明 |
| ---- | ---- |
| **明确目标** | 清晰说明想要什么 |
| **提供上下文** | 给出必要的背景信息 |
| **结构清晰** | 使用分段和列表 |
| **具体约束** | 明确限制和要求 |
| **示例引导** | 用示例说明期望 |

---

## 针对不同场景的提示词

### 1. 前端开发

```
请创建一个 React + TypeScript 的用户列表组件：

需求：
- 使用 TypeScript 定义 User 类型：{ id, name, email, avatar }
- 使用 shadcn/ui 的 Table 组件展示用户列表
- 支持分页（每页 10 条）
- 支持按姓名搜索
- 点击行可查看用户详情

API 接口：GET /api/users?page=1&limit=10&search=keyword
返回格式：{ data: User[], total: number }

请提供完整组件代码和必要的类型定义。
```

### 2. 后端开发

```
请用 Node.js + Express 创建一个用户认证 API：

需求：
- POST /api/auth/register - 用户注册
- POST /api/auth/login - 用户登录
- POST /api/auth/logout - 用户登出
- GET /api/auth/me - 获取当前用户信息

技术要求：
- 使用 TypeScript
- 使用 Prisma ORM
- 使用 JWT 进行认证
- 密码使用 bcrypt 加密
- 数据库使用 PostgreSQL

数据模型（User）：
- id: UUID
- email: 唯一
- password: 加密存储
- name: 用户名
- createdAt: 创建时间

请提供完整的路由、控制器和中间件代码。
```

### 3. 数据分析

```
请帮我分析以下数据：

销售数据：
```
月份,Q1,Q2,Q3,Q4
产品A,120,150,180,200
产品B,80,90,100,110
产品C,200,180,150,120
```

请提供：
1. 季度增长趋势分析
2. 产品表现对比
3. 潜在问题识别
4. 改进建议

使用 Markdown 格式输出，包含数据可视化建议。
```

### 4. 文档生成

```
请为以下 API 生成 Swagger/OpenAPI 文档：

API 端点：POST /api/users

请求体：
{
  "email": "string (required, email format)",
  "password": "string (required, minLength: 8)",
  "name": "string (required)"
}

成功响应（201）：
{
  "id": "uuid",
  "email": "string",
  "name": "string",
  "createdAt": "datetime"
}

错误响应：
- 400: 参数验证失败
- 409: 邮箱已存在

请生成完整的 OpenAPI 3.0 规范（YAML 格式）。
```

---

## 提示词迭代优化

### 迭代流程

```
第一版（基础版）
"写一个登录功能"
      ↓
      ❌ 结果不符合预期
      ↓
第二版（添加细节）
"用 React 写一个登录表单，包含邮箱和密码"
      ↓
      ⚠️ 接近了，但还不完美
      ↓
第三版（精细化）
"请创建一个 React + TypeScript 登录表单，使用 shadcn/ui..."
      ↓
      ✅ 满意
```

### 迭代技巧

1. **从简单开始**：先给基础版本
2. **逐步添加细节**：一次只加一个要求
3. **观察输出**：分析不符合预期的部分
4. **针对性修正**：指出具体问题
5. **验证结果**：确认是否满足需求

---

## 参考资源

### 官方文档

- [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)
- [Anthropic Prompt Library](https://docs.anthropic.com/prompt-library)
- [Google Prompting Guide](https://ai.google.dev/gemini-api/prompting-strategies)

### 学习资源

- [Learn Prompting](https://learnprompting.org/)
- [Prompt Engineering Guide](https://www.promptingguide.ai/)

### 社区资源

- [Awesome Prompt Engineering](https://github.com/f/awesome-prompt-engineering)
- [Prompt Examples](https://github.com/matthew-burrell/prompt-examples)

---

**文档更新时间：2025 年 12 月**

---

## RAG（检索增强生成）


## 概述

**RAG (Retrieval-Augmented Generation)** 是一种结合了**信息检索（Retrieval）**和**生成式AI（Generation）**的技术架构。它让大语言模型在生成回答时，能够先从外部知识库中检索相关信息，然后基于检索到的内容生成更准确、更及时的回答。

> **核心价值**：解决 LLM 的知识滞后和幻觉问题，让 AI 拥有"外挂知识库"

---

## RAG 的核心概念

### 1. 为什么需要 RAG

```
纯 LLM 的问题:
├── 知识截止：训练数据有时间边界
├── 幻觉问题：可能生成不准确的内容
├── 领域知识：缺乏专业领域的私有数据
└── 可追溯性：无法验证信息来源

RAG 的解决:
├── 实时知识：可检索最新信息
├── 准确性：基于真实文档生成
├── 私有数据：可接入企业内部知识
└── 可验证：提供信息来源引用
```

### 2. RAG vs Fine-tuning

| 维度 | RAG | Fine-tuning（微调） |
| ---- | --- | ------------------- |
| **知识更新** | 实时更新 | 需要重新训练 |
| **数据来源** | 外部知识库 | 模型权重 |
| **实施成本** | 低 | 高 |
| **幻觉控制** | 好 | 中 |
| **领域适应** | 快速适应 | 需要训练数据 |
| **隐私安全** | 数据不进入模型 | 数据融入模型 |
| **适用场景** | 知识查询、问答 | 风格适应、格式化 |

---

## RAG 的工作原理

### 1. 基本流程

```
┌─────────────────────────────────────────────────────────────────┐
│                         RAG 工作流程                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  用户问题                                                        │
│    │                                                            │
│    ▼                                                            │
│  ┌─────────────────┐                                           │
│  │  向量化 (Embedding) │                                          │
│  │  问题 → 向量      │                                           │
│  └─────────────────┘                                           │
│    │                                                            │
│    ▼                                                            │
│  ┌─────────────────┐                                           │
│  │  相似度检索      │                                           │
│  │  在向量库中搜索  │                                           │
│  └─────────────────┘                                           │
│    │                                                            │
│    ▼                                                            │
│  ┌─────────────────┐                                           │
│  │  获取相关文档    │                                           │
│  │  Top-K 结果     │                                           │
│  └─────────────────┘                                           │
│    │                                                            │
│    ▼                                                            │
│  ┌─────────────────┐                                           │
│  │  Prompt 构建     │                                           │
│  │  问题 + 文档上下文│                                           │
│  └─────────────────┘                                           │
│    │                                                            │
│    ▼                                                            │
│  ┌─────────────────┐                                           │
│  │  LLM 生成回答    │                                           │
│  │  基于检索内容    │                                           │
│  └─────────────────┘                                           │
│    │                                                            │
│    ▼                                                            │
│  带引用的回答                                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 2. 关键组件

#### 向量嵌入 (Embedding)

```
文本: "人工智能是计算机科学的一个分支"
       │
       ▼
   向量化模型 (如 OpenAI Embeddings)
       │
       ▼
向量: [0.123, -0.456, 0.789, ...]  (1536 维)
```

#### 向量数据库 (Vector Database)

| 数据库 | 特点 |
| ------ | ---- |
| **Pinecone** | 托管服务，易用 |
| **Chroma** | 轻量级，本地部署 |
| **Qdrant** | 高性能，开源 |
| **Milvus** | 企业级，可扩展 |
| **Weaviate** | 支持多种数据类型 |

#### 相似度计算

```python
# 余弦相似度
similarity = cosine_similarity(query_vector, document_vector)

# 欧氏距离
distance = euclidean_distance(query_vector, document_vector)
```

---

## RAG 的实现方式

### 1. Naive RAG（基础 RAG）

最简单的 RAG 实现：

```python
# 伪代码
def naive_rag(query):
    # 1. 向量化查询
    query_vector = embedding_model.encode(query)

    # 2. 检索相关文档
    docs = vector_db.search(query_vector, top_k=5)

    # 3. 构建 Prompt
    prompt = f"""
    基于以下文档回答问题：

    {docs}

    问题：{query}
    """

    # 4. 生成回答
    answer = llm.generate(prompt)
    return answer
```

### 2. Advanced RAG（高级 RAG）

包含更多优化技术：

```
┌─────────────────────────────────────────────────────────┐
│                    Advanced RAG                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  查询理解                                                │
│  ├── 查询重写 (Query Rewriting)                         │
│  ├── 查询扩展 (Query Expansion)                         │
│  ├── 查路由 (Query Routing)                             │
│  └── 多重查询 (Multi-Query)                             │
│         ↓                                               │
│  混合检索                                                │
│  ├── 向量检索 (Semantic Search)                         │
│  ├── 关键词检索 (Keyword Search)                        │
│  └── 结果融合 (Result Fusion)                           │
│         ↓                                               │
│  重排序 (Reranking)                                      │
│  └── 使用更精细的模型重新排序                            │
│         ↓                                               │
│  上下文管理                                              │
│  ├── 长上下文压缩                                        │
│  └── 动态选择相关片段                                    │
│         ↓                                               │
│  生成回答                                                │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 3. Modular RAG（模块化 RAG）

可灵活组合的 RAG 模块：

```
RAG 模块:
├── 检索模块
│   ├── 单路检索
│   ├── 递归检索
│   └── 混合检索
├── 生成模块
│   ├── 单次生成
│   ├── 迭代生成
│   └── 分步生成
└── 优化模块
    ├── 查询优化
    ├── 文档优化
    └── 结果优化
```

---

## RAG 的优化技术

### 1. 查询优化

#### 查询重写

```python
# 原始查询
"怎么用这个功能"

# 重写后
"如何使用 [产品名称] 的 [具体功能名称]？"
```

#### 多重查询

```python
# 生成多个查询变体
query_variants = [
    "人工智能的发展历史",
    "AI 发展历程",
    "机器学习和深度学习的起源"
]
# 并行检索后合并结果
```

#### 查询路由

```python
def route_query(query):
    if is_code_question(query):
        return "code_kb_index"
    elif is_business_question(query):
        return "business_kb_index"
    else:
        return "general_kb_index"
```

### 2. 文档优化

#### 分块策略 (Chunking)

```python
# 固定大小分块
chunk_size = 512
overlap = 50

# 语义分块（按段落、章节）
chunks = split_by_semantic_unit(document)

# 递归分块
chunks = recursive_split(document, max_length=1000)
```

#### 元数据增强

```python
{
    "content": "文档内容...",
    "metadata": {
        "source": "user_manual.pdf",
        "page": 15,
        "chapter": "安装指南",
        "last_updated": "2024-01-15",
        "author": "技术文档团队"
    }
}
```

### 3. 检索优化

#### 混合检索

```python
# 结合向量检索和关键词检索
vector_results = vector_search(query, top_k=10)
keyword_results = bm25_search(query, top_k=10)

# 结果融合
final_results = reciprocal_rank_fusion(vector_results, keyword_results)
```

#### 重排序 (Reranking)

```python
# 初步检索
initial_results = vector_db.search(query, top_k=50)

# 使用更强的模型重排序
reranker = CrossEncoderReranker()
final_results = reranker.rerank(query, initial_results, top_k=10)
```

### 4. 生成优化

#### 引用生成

```markdown
根据以下内容回答，并标注引用来源：

[文档1] 我们app支持 iOS 和 Android...
[文档2] 安装包大小约为 50MB...
[文档3] 需要注册账户才能使用...

问题：这个应用支持哪些平台？

回答：该应用支持 iOS 和 Android 平台 [1]。
```

#### 自我修正 (Self-RAG)

```
生成回答 → 检查相关性 → 检查支持性 →
如果不相关/不支持 → 重新检索 → 重新生成
```

---

## RAG 的应用场景

### 1. 企业知识库

```
员工: "公司的报销流程是什么？"
   ↓
RAG: [从员工手册、OA系统文档中检索]
   ↓
回答: "根据《员工手册》第5章，
       报销流程如下：1.提交申请 2.主管审批..."
       来源: employee-handbook.pdf, page 23
```

### 2. 客户服务

```
客户: "产品如何保修？"
   ↓
RAG: [从产品手册、售后政策中检索]
   ↓
回答: "本产品提供2年质保，
       保修范围包括..."
       来源: warranty-policy.html
```

### 3. 代码助手

```
开发者: "这个项目怎么用 Webpack 构建？"
   ↓
RAG: [从项目 README、文档中检索]
   ↓
回答: "根据项目文档，
       运行 pnpm build 即可..."
       来源: README.md, docs/build.md
```

### 4. 技术文档问答

```
用户: "TailwindCSS 怎么在小程序中使用？"
   ↓
RAG: [从 weapp-tailwindcss 文档中检索]
   ↓
回答: "在 weapp-tailwindcss 中，
       配置 postcss.config.js..."
       来源: docs/getting-started.md
```

---

## RAG 的评估指标

### 1. 检索质量

| 指标 | 说明 |
| ---- | ---- |
| **Precision@K** | 前K个结果中有多少是相关的 |
| **Recall@K** | 所有相关文档中检索到了多少 |
| **MRR** | 第一个相关结果的倒数排名 |
| **NDCG** | 考虑位置的相关性评分 |

### 2. 生成质量

| 指标 | 说明 |
| ---- | ---- |
| **Faithfulness** | 回答是否与检索内容一致 |
| **Answer Relevance** | 回答是否解决了问题 |
| **Context Precision** | 检索的上下文是否相关 |
| **Context Recall** | 是否检索到了所有必要信息 |

### 3. 端到端评估

```python
# RAG 评估框架示例
from ragas import evaluate

results = evaluate(
    dataset=test_dataset,
    metrics=[
        "faithfulness",
        "answer_relevancy",
        "context_precision",
        "context_recall"
    ]
)
```

---

## RAG 的常见问题

### 1. 检索不到相关内容

**原因**：
- 向量质量差
- 分块策略不当
- 知识库内容缺失

**解决**：
- 使用更好的 Embedding 模型
- 调整分块大小和重叠
- 补充知识库内容
- 使用混合检索

### 2. 回答不准确

**原因**：
- 检索内容不相关
- 上下文过长导致注意力分散
- 模型理解能力不足

**解决**：
- 提高检索精度（重排序）
- 压缩上下文
- 使用更强的生成模型

### 3. 回答缺少引用

**原因**：
- Prompt 设计不当
- 模型未遵循指令

**解决**：
- 明确要求标注来源
- 使用结构化输出
- 后处理添加引用链接

---

## RAG 开源框架

### 1. LangChain

```python
from langchain.chains import RetrievalQA
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

# 创建 RAG 链
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectordb.as_retriever(search_kwargs={"k": 3}),
    return_source_documents=True
)
```

### 2. LlamaIndex

```python
from llama_index import VectorStoreIndex, SimpleDirectoryReader

# 创建索引
documents = SimpleDirectoryReader('data').load_data()
index = VectorStoreIndex.from_documents(documents)

# 查询
query_engine = index.as_query_engine()
response = query_engine.query("问题")
```

### 3. Haystack

```python
from haystack import Pipeline, Document
from haystack.nodes import BM25Retriever, FARMReader

# 创建 RAG Pipeline
retriever = BM25Retriever(document_store)
reader = FARMReader(model_name="deepset/roberta-base-squad2")

pipe = Pipeline()
pipe.add_node(retriever, name="Retriever", inputs=["Query"])
pipe.add_node(reader, name="Reader", inputs=["Retriever"])
```

### 4. FastRAG / RAGFlow

专注于 RAG 的轻量级框架。

---

## RAG 实现清单

### 数据准备

- [ ] 收集文档数据
- [ ] 清洗和预处理
- [ ] 选择分块策略
- [ ] 添加元数据

### 向量化

- [ ] 选择 Embedding 模型
- [ ] 选择向量数据库
- [ ] 构建向量索引
- [ ] 测试检索质量

### Prompt 设计

- [ ] 设计系统提示词
- [ ] 定义输出格式
- [ ] 添加引用要求
- [ ] 处理无结果情况

### 评估优化

- [ ] 准备测试数据集
- [ ] 评估检索质量
- [ ] 评估生成质量
- [ ] 迭代优化

---

## 参考资源

### 论文

- [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) - RAG 原始论文
- [Building RAG-based Applications with LangChain](https://blog.langchain.dev/building-a-full-rag-application-with-langchain/)

### 工具

- [LangChain](https://langchain.com) - AI 应用开发框架
- [LlamaIndex](https://llamaindex.ai) - 数据框架
- [Pinecone](https://pinecone.io) - 向量数据库
- [Qdrant](https://qdrant.tech) - 开源向量数据库

### 学习资源

- [RAG Tutorial](https://github.com/langchain-ai/rag-from-scratch)
- [Building RAG Applications](https://www.deeplearning.ai/short-courses/building-evaluating-advanced-rag/)

---

**文档更新时间：2025 年 12 月**

---

## Skill 发布与版本化


本页面面向 `weapp-tailwindcss` Skill 维护者，说明如何做版本管理、打 tag、发 release，并保持安装指令稳定可用。

## 适用对象

- 维护 `skills/weapp-tailwindcss/SKILL.md` 的仓库维护者
- 需要在 AI 学习中心持续展示可用安装命令的文档维护者

## 发布前检查

1. 确认技能文件已更新

```text
skills/weapp-tailwindcss/SKILL.md
```

2. 本地校验技能可被发现

```bash
npx skills add . --list
```

3. 本地校验技能可被安装

```bash
npx skills add . --skill weapp-tailwindcss
```

4. 校验 AI 学习中心文档已同步

- `website/docs/ai/basics/skill.md`
- `README.md`

## 推荐版本策略

- 使用独立语义化版本 tag 管理 Skill 变更，例如 `skill-weapp-tailwindcss-v1.0.0`
- 变更类型建议：
  - Patch：文案修订、轻微流程修正
  - Minor：新增框架支持或新增标准排障流程
  - Major：删除旧流程或发生不兼容调整

## 发布流程（tag + GitHub Release）

1. 提交并推送代码

```bash
git checkout main
git pull --rebase
git add skills/weapp-tailwindcss/SKILL.md website/docs/ai/basics/skill.md README.md
git commit -m "docs(skill): 更新 weapp-tailwindcss 用户技能"
git push origin main
```

2. 创建并推送 tag

```bash
git tag -a skill-weapp-tailwindcss-v1.0.0 -m "release: weapp-tailwindcss skill v1.0.0"
git push origin skill-weapp-tailwindcss-v1.0.0
```

3. 创建 GitHub Release（任选一种）

- Web UI：在 GitHub 仓库的 Releases 页面基于上述 tag 创建
- `gh` CLI：

```bash
gh release create skill-weapp-tailwindcss-v1.0.0 \
  --title "weapp-tailwindcss skill v1.0.0" \
  --notes "更新内容：补充多端项目接入流程与排障提示。"
```

## AI 学习中心展示规范

为了降低用户学习成本，安装命令建议保持固定：

```bash
npx skills add sonofmagic/skills --skill weapp-tailwindcss
```

每次 Skill 行为发生变更时，同步更新以下入口：

- `website/docs/ai/basics/skill.md`
- `website/docs/ai/index.md`
- `README.md`

---

## Skill（技能系统）


## 概述

Skill 是一组可复用的执行规则与工作流，用来让 AI 在特定任务中更稳定地输出结果。

`weapp-tailwindcss` 提供的 Skill 目标是帮助用户在自己的业务项目中，快速接入并稳定使用 `weapp-tailwindcss`，用于小程序与多端开发。

> 这个 Skill 主要服务“项目使用者”，不是仓库二次开发维护指南。

在本项目中，我们采用 [`vercel-labs/skills`](https://github.com/vercel-labs/skills) 安装 Skill，技能文件为 `SKILL.md`。

## weapp-tailwindcss Skill 安装

### 1. 从 GitHub 安装（推荐）

```bash
npx skills add sonofmagic/skills --skill weapp-tailwindcss
```

### 2. 查看仓库可安装 Skill 列表

```bash
npx skills add sonofmagic/skills --list
```

### 3. 本地开发时安装当前目录 Skill

在本仓库根目录执行：

```bash
npx skills add . --skill weapp-tailwindcss
```

## 装完后能做什么

安装后，你可以让 AI 按你的项目类型直接产出可运行配置，例如：

- `uni-app cli vue3 vite` 项目接入方案
- `taro webpack5` / `taro vite` 项目接入方案
- `uni-app x` 同时构建 `Web` / 小程序 / `Android` / `iOS` / 鸿蒙
- 已有项目迁移、样式失效排障、`rpx` 任意值问题定位
- Tailwind 写法规范沉淀（含 `space-y-*` / `space-x-*` 在小程序端的标签限制与修复顺序）

Skill 会要求 AI 优先完成这些关键动作：

- 识别你当前框架和目标端
- 补齐 `tailwindcss` 与 `weapp-tailwindcss` 最小可用配置
- 明确 `postinstall` 中的 `weapp-tw patch`
- 给出“可复制命令 + 可复制配置 + 验证步骤”
- 对 `space-y-*` / `space-x-*` 问题按固定优先级排查：先改结构，再评估 `virtualHost`，最后扩展 `cssChildCombinatorReplaceValue`

## Skill 执行流程（更新）

当前 `weapp-tailwindcss` Skill 会把请求先分流，再输出结果：

1. 任务分流：新项目接入、存量迁移、问题排查、写法规范沉淀
2. 信息收集最小集：
   - 框架（`uni-app` / `taro` / `uni-app x` / 原生）
   - 构建器（`vite` / `webpack5` / `webpack4`）
   - 目标端（仅小程序 / 小程序 + `H5/App`）
   - Tailwind 版本（v3/v4）与包管理器（重点 `pnpm@10+`）
   - Node 版本（建议 `^20.19.0 || >=22.12.0`）
3. 按任务读取对应参考文件：
   - 集成/迁移：`references/integration-playbook.md`
   - 排障：`references/troubleshooting-playbook.md`
   - 写法规范：`references/tailwind-writing-best-practices.md`

## Skill 输出标准（更新）

Skill 输出会强制包含以下项目，避免只给概念不落地：

1. 结论（适用框架、Tailwind 版本、目标端）
2. 修改文件清单
3. 可直接复制的配置片段
4. 安装/运行命令（默认 `pnpm`）
5. 验证步骤与预期结果
6. 回滚方案（至少一条）

## 写法规范补充：space-y / space-x

在小程序里，`space-y-*`、`space-x-*` 这类依赖子组合器的工具类，默认不是“全标签通用”，通常会按 `view + view`（含 `text`）处理。

如果你遇到 `space-y-2` 不生效，建议按下面顺序处理：

1. 先改结构：让相邻子节点落在 `view/text`，或外层包一层 `view`
2. 再评估组件层：自定义组件场景启用 `virtualHost`
3. 最后改配置：仅在必要时扩展 `cssChildCombinatorReplaceValue`，并保持最小化标签范围

## 推荐提示词

1. 新项目快速接入

```text
我现在是 uni-app cli vue3 vite 项目，目标端是微信小程序 + H5。
请按 weapp-tailwindcss skill 给我最小可用配置，
输出需要包含：安装命令、完整配置文件、验证步骤。
```

2. 旧项目迁移

```text
这是一个 taro webpack5 老项目，已经有 tailwindcss 但样式经常丢失。
请按 weapp-tailwindcss skill 给迁移方案，并列出最小改动清单。
```

3. 问题排查

```text
我在 JS 字符串里写了 tailwind 任意值 class，但小程序端不生效。
请按 weapp-tailwindcss skill 给排查顺序，并指出应该检查的配置项。
```

4. `space-y` / `space-x` 不生效排查

```text
我的容器写了 space-y-2，但子节点是 button 和自定义组件，间距没有生效。
请按 weapp-tailwindcss skill 给固定优先级排查方案，并给出最小改动配置。
```

5. 要求带回滚方案

```text
这是一个 uni-app vite 项目，请按 weapp-tailwindcss skill 给我迁移方案。
输出必须包含：改动文件、可复制配置、验证步骤、回滚方案。
```

## Skill 文件位置

```text
skills/weapp-tailwindcss/SKILL.md
```

## Skill 参考文件位置

```text
skills/weapp-tailwindcss/references/integration-playbook.md
skills/weapp-tailwindcss/references/troubleshooting-playbook.md
skills/weapp-tailwindcss/references/tailwind-writing-best-practices.md
```

## 常见问题

### 安装后看不到 Skill

排查顺序：

1. 先执行 `npx skills add <repo> --list` 确认技能名。
2. 确认安装命令中的 `--skill weapp-tailwindcss` 名称完全一致。
3. 确认默认分支已包含 `skills/weapp-tailwindcss/SKILL.md`。

### 我是 Skill 维护者，如何发布版本

请查看：[Skill 发布与版本化](/docs/ai/basics/skill-release)

---

## Spec-Driven Development（规范驱动开发）


## 概述

**Spec-Driven Development (SDD)** 或 **Spec-Driven Coding** 是一种**以规范（Specification）为先导**的软件开发方法论。开发者先编写详细的需求规范，然后由 AI 根据规范自动生成代码。

> **核心理念**：明确规范 → 自动实现 → 减少沟通成本

---

## 核心概念

### 1. 什么是 Spec（规范）

**Spec** 是对软件功能的**精确、可执行的描述**：

```markdown
# 用户登录功能规范

## 功能描述
用户可以使用邮箱和密码登录系统。

## 输入
- email: 字符串，符合邮箱格式
- password: 字符串，8-32位，包含字母和数字

## 输出
- 成功：返回用户信息和 JWT token
- 失败：返回错误信息

## 验证规则
- 邮箱必须已注册
- 密码必须正确
- 连续失败5次后锁定账户30分钟

## API 端点
POST /api/auth/login
```

### 2. Spec-Driven vs 传统开发

| 开发方式 | 流程 | 优势 | 劣势 |
| -------- | ---- | ---- | ---- |
| **传统开发** | 需求 → 设计 → 编码 | 灵活 | 沟通成本高 |
| **Spec-Driven** | 规范 → AI 生成代码 | 自动化、可追溯 | 需要编写规范 |
| **敏捷开发** | 用户故事 → 迭代 | 快速响应 | 文档缺失 |

---

## Spec-Driven Development 的流程

```
┌─────────────────────────────────────────────────────────┐
│              Spec-Driven Development 流程                │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. 需求收集                                           │
│     │                                                   │
│     ▼                                                   │
│  2. 编写规范 (Spec)        ┌─────────────────┐          │
│     │                     │  自然语言规范    │          │
│     ├────────────────────▶│  API 规范       │          │
│     │                     │  数据模型规范   │          │
│     │                     │  UI 规范        │          │
│     │                     └─────────────────┘          │
│     │                                                   │
│     ▼                                                   │
│  3. AI 代码生成         ┌─────────────────┐          │
│     │                     │ Claude Code     │          │
│     ├────────────────────▶│ Cursor Agent    │          │
│     │                     └─────────────────┘          │
│     │                                                   │
│     ▼                                                   │
│  4. 代码审查                                           │
│     │                                                   │
│     ▼                                                   │
│  5. 测试验证                                           │
│     │                                                   │
│     ▼                                                   │
│  6. 部署上线                                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Spec 的类型

### 1. 功能规范

描述软件应该做什么：

```markdown
## 功能：用户注册

### 需求
用户可以注册新账户

### 输入字段
- username: 3-20字符，字母数字下划线
- email: 有效的邮箱地址
- password: 最少8位，必须包含大小写字母和数字

### 业务规则
- 用户名必须唯一
- 邮箱必须未被注册
- 注册后自动发送验证邮件
```

### 2. API 规范

描述 API 接口：

```yaml
# OpenAPI 规范
openapi: 3.0.0
info:
  title: 用户认证 API
  version: 1.0.0

paths:
  /auth/login:
    post:
      summary: 用户登录
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: 登录成功
```

### 3. 数据模型规范

描述数据结构：

```typescript
// TypeScript 接口规范
interface User {
  id: string;
  username: string;
  email: string;
  createdAt: Date;
  updatedAt: Date;
}

interface LoginRequest {
  email: string;
  password: string;
}

interface LoginResponse {
  success: boolean;
  token?: string;
  user?: User;
  error?: string;
}
```

### 4. UI 规范

描述界面要求：

```markdown
## 登录页面 UI 规范

### 布局
- 居中卡片式布局
- 宽度 400px

### 组件
- 邮箱输入框
- 密码输入框（带显示/隐藏切换）
- "记住我" 复选框
- "忘记密码" 链接
- 登录按钮

### 样式
- 主色调：#3B82F6
- 圆角：8px
- 阴影：0 4px 6px rgba(0,0,0,0.1)
```

---

## 支持 Spec-Driven 的工具

### 1. Cursor Composer

Cursor 的多步骤任务执行：

```typescript
// 用户输入
"实现用户认证功能，包含注册、登录、登出"

// Cursor 自动规划
1. 分析需求 → 生成规范
2. 设计数据模型
3. 实现 API 端点
4. 创建 UI 组件
5. 编写测试用例
```

### 2. Claude Code CLI

通过 CLAUDE.md 定义规范：

```markdown
# 项目规范

## 编码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 规则
- 组件使用函数式声明

## API 规范
- RESTful 风格
- 统一错误处理
- JWT 认证

## 测试规范
- 单元测试覆盖率 > 80%
- 使用 Vitest
```

---

## Spec 编写最佳实践

### 1. SMART 原则

| 原则 | 说明 | 示例 |
| ---- | ---- | ---- |
| **Specific** | 具体明确 | "用户可以登录" 而非 "实现认证" |
| **Measurable** | 可衡量 | "密码8-32位" 而非 "密码足够复杂" |
| **Achievable** | 可实现 | 考虑技术限制 |
| **Relevant** | 相关性 | 与业务目标一致 |
| **Time-bound** | 有时限 | "在2秒内完成" |

### 2. 结构化规范

```markdown
## 功能概述
一句话描述功能

## 用户故事
作为 [角色]，我想要 [功能]，以便 [目的]

## 验收标准
- [ ] 场景1：描述
- [ ] 场景2：描述

## 技术规范
### 数据模型
### API 接口
### 业务逻辑

## 非功能需求
### 性能：响应时间 < 200ms
### 安全：HTTPS + JWT
### 兼容：支持主流浏览器
```

### 3. 使用规范语言

- 使用**自然语言**但保持结构化
- 避免歧义词汇（"尽可能"、"大概"）
- 使用**具体数字**（"3次"而非"多次"）
- 包含**边界条件**（"空值"、"超长输入"）

---

## Spec-Driven vs 其他开发方式

### Spec-Driven vs Vibe Coding

| 维度 | Spec-Driven | Vibe Coding |
| ---- | ----------- | ----------- |
| **规划** | 详细规范 | 随性发挥 |
| **可追溯** | 高 | 低 |
| **团队协作** | 容易 | 困难 |
| **AI 参与** | 核心 | 辅助 |
| **适用场景** | 大型项目、团队 | 原型、个人项目 |

### Spec-Driven vs Test-Driven Development

| 维度 | Spec-Driven | TDD |
| ---- | ----------- | --- |
| **起点** | 规范 | 测试 |
| **顺序** | 规范 → 代码 → 测试 | 测试 → 代码 |
| **AI 友好** | 是 | 否 |
| **可组合** | 可组合 | 相对独立 |

---

## 实施建议

### 1. 规范模板

```markdown
# [功能名称] 规范

## 背景
为什么需要这个功能

## 目标
这个功能要达到什么效果

## 功能描述
详细的功能说明

## 验收标准
如何判断功能完成

## 技术考虑
- 性能要求
- 安全考虑
- 兼容性要求

## 依赖
依赖的其他功能或模块
```

### 2. 工具配置

```json
// .claude/spec-template.json
{
  "template": "# 功能规范\n\n## 功能概述\n{summary}\n\n## 需求\n{requirements}\n\n## 验收标准\n{acceptance}",
  "requiredFields": ["summary", "requirements"],
  "outputFormat": "markdown"
}
```

### 3. 版本管理

```
specs/
├── v1.0/
│   ├── auth-spec.md
│   ├── user-spec.md
│   └── api-spec.md
├── v1.1/
│   ├── auth-spec.md (更新)
│   └── payment-spec.md (新增)
```

---

## 参考资源

### 相关工具

- [Cursor Composer](https://cursor.com/docs/composer)
- [OpenAPI Specification](https://swagger.io/specification/)

### 相关方法论

- [Behavior-Driven Development (BDD)](https://en.wikipedia.org/wiki/Behavior-driven_development)
- [Feature-Driven Development (FDD)](https://en.wikipedia.org/wiki/Feature-driven_development)

---

**文档更新时间：2025 年 12 月**

---

## Token（词元）


## 概述

**Token** 是大语言模型（LLM）处理文本的**基本单位**。不同于人类理解的"单词"或"字符"，Token 是模型内部使用的最小语义单元。

> **核心概念**：1 Token ≈ 0.75 个英文单词 ≈ 4 个字符 ≈ 2-3 个汉字

---

## Token 的本质

### 1. 什么是 Token

Token 是将文本切分成的**序列片段**：

```
输入文本: "Hello, world!"
Token序列: ["Hello", ",", "world", "!"]
Token数量: 4
```

### 2. 分词 (Tokenization)

将文本转换为 Token 序列的过程：

```python
# GPT 分词示例
text = "Artificial Intelligence is amazing"
tokens = ["Art", "ificial", " Int", "elligence", " is", " am", "azing"]
# 7 tokens

# Claude 分词示例
text = "Artificial Intelligence is amazing"
tokens = ["Art", "ificial", " Intelligence", " is", " amazing"]
# 5 tokens（不同模型分词不同）
```

### 3. 字节对编码 (BPE)

主流的 Tokenization 方法：

```
原始: "unbelievable"
步骤1: u n b e l i e v a b l e (字符级)
步骤2: un bel ieve able (词级+字符级混合)
步骤3: ["un", "believable"] (最终Token)
```

---

## Token 的计数规则

### 1. 英文文本

| 文本类型 | Token 估算 |
| -------- | ---------- |
| 1 个单词 | ~1.3 tokens |
| 1 个句子 (15词) | ~20 tokens |
| 1 段落 (100词) | ~130 tokens |
| 1 页文档 (500词) | ~650 tokens |

### 2. 中文文本

| 文本类型 | Token 估算 |
| -------- | ---------- |
| 1 个汉字 | ~0.5-1 token |
| 1 个词 (2-3字) | ~1-2 tokens |
| 1 个句子 (20字) | ~10-15 tokens |
| 1 段落 (100字) | ~50-70 tokens |

### 3. 代码

| 代码类型 | Token 估算 |
| -------- | ---------- |
| 1 行简单代码 | ~10-20 tokens |
| 1 行复杂代码 | ~30-50 tokens |
| 1 个函数 (50行) | ~300-500 tokens |
| 1 个文件 (500行) | ~3000-5000 tokens |

### 4. 特殊场景

| 场景 | Token 计数 |
| ---- | ---------- |
| 空格 | 1 token |
| 换行 | 1 token |
| 缩进 (2空格) | 1 token |
| 制表符 | 1 token |
| 数字 (12345) | 1-2 tokens |
| URL | ~10-20 tokens |

---

## 各模型的 Token 限制

### 上下文窗口 (Context Window)

| 模型 | 上下文长度 | 输出限制 |
| ---- | ---------- | -------- |
| **Claude Opus 4.5** | 200K tokens | ~8K 输出 |
| **Claude Sonnet 4.5** | 200K tokens | ~8K 输出 |
| **GPT-4o** | 128K tokens | ~4K 输出 |
| **GPT-5.2** | 1M tokens | ~8K 输出 |
| **Gemini 2.0 Pro** | 2M tokens | ~8K 输出 |
| **Gemini 1.5 Pro** | 1M tokens | ~8K 输出 |
| **GLM-4.7** | 128K tokens | ~4K 输出 |

### Token 价格对比（$/百万 tokens）

| 模型 | 输入 | 输出 |
| ---- | ---- | ---- |
| **Claude Opus 4.5** | $15 | $75 |
| **Claude Sonnet 4.5** | $3 | $15 |
| **GPT-4o** | $5 | $15 |
| **GPT-5.2** | $2 | $8 |
| **Gemini 2.0 Pro** | $1.25 | $5 |
| **GLM-4.7** | ¥2.2 (≈$0.3) | ¥6.6 (≈$0.9) |

---

## Token 实用计算

### 1. 快速估算

```
英文: 字符数 ÷ 4 ≈ Token 数
中文: 字符数 ÷ 2 ≈ Token 数
代码: 行数 × 10 ≈ Token 数
```

### 2. 精确计算工具

#### Tiktoken (OpenAI)

```python

# GPT-4 编码器
encoding = tiktoken.encoding_for_model("gpt-4")
text = "Hello, world!"
tokens = encoding.encode(text)
print(f"Token 数量: {len(tokens)}")
```

#### Anthropic Tokenizer

```python

client = anthropic.Anthropic()
response = client.messages.count_tokens(
    model="claude-3-opus-20240229",
    text="Hello, world!"
)
print(f"Token 数量: {response.input_tokens}")
```

#### 在线工具

- [Token 计算](https://platform.openai.com/tokenizer)
- [Claude Token 计数](https://calculator.anthropic.com/)

---

## Token 使用优化

### 1. 减少 Token 消耗

| 优化方法 | 效果 |
| -------- | ---- |
| **删除无用信息** | 节省 20-40% |
| **精简提示词** | 节省 30-50% |
| **使用压缩格式** | 节省 10-20% |
| **避免重复内容** | 节省 15-30% |

### 2. 系统提示词优化

```diff
- verbose: "You are a highly intelligent and capable assistant designed to help users with a wide variety of tasks..."
+ concise: "你是一个智能助手，擅长代码开发和问题解决。"
```

### 3. 上下文管理

```python
# 只包含相关文件
relevant_files = [
    "src/utils/auth.ts",    # 包含
    "src/utils/helpers.ts", # 包含
    # "src/utils/deprecated.ts", # 排除
]

# 使用摘要代替全文
file_summary = summarize_large_file("large_file.ts")  # 100 tokens
# vs 完整文件: # 5000 tokens
```

### 4. 缓存策略

| 缓存类型 | 说明 | 节省 |
| -------- | ---- | ---- |
| **系统提示缓存** | Claude/GPT 支持 | 可重用 |
| **文档缓存** | 预处理文档 | 减少重复输入 |
| **向量检索** | 只取相关片段 | 大幅减少上下文 |

---

## Token 成本计算

### 1. 成本估算示例

假设使用 GPT-4o 分析代码库：

```
代码库规模: 100,000 行代码
Token 估算: 100,000 × 10 = 1,000,000 tokens
输入成本: 1M × $5/1M = $5
输出成本: 50K × $15/1M = $0.75
总成本: ~$6
```

### 2. 不同模型成本对比

假设处理 1M tokens：

| 模型 | 输入成本 | 总成本 |
| ---- | -------- | ------ |
| **Claude Opus 4.5** | $15 | ~$90 |
| **Claude Sonnet 4.5** | $3 | ~$18 |
| **GPT-4o** | $5 | ~$30 |
| **GPT-5.2** | $2 | ~$12 |
| **Gemini 2.0 Pro** | $1.25 | ~$7.50 |
| **GLM-4.7** | ¥2.2 (≈$0.3) | ~¥15 (≈$2) |

---

## Token 常见问题

### Q1: 为什么中英文 Token 数不同？

中文使用 Unicode 编码，一个汉字可能被拆分成多个字节，因此需要更多或更少的 tokens。

### Q2: 空格和换行算 Token 吗？

是的，空格、换行、缩进等空白字符都会被计入 tokens。

### Q3: 代码注释是否计入 Token？

是的，所有发送给模型的内容都会计入，包括注释。

### Q4: 如何减少 API 成本？

- 使用更小的模型（如 Sonnet 代替 Opus）
- 优化提示词长度
- 使用缓存和向量化
- 批量处理

### Q5: Token 和字符的精确比例？

| 语言 | Token/字符 |
| ---- | ---------- |
| 英文 | ~1:4 |
| 中文 | ~1:2 |
| 代码 | ~1:3-5 |

---

## 参考资源

### 官方文档

- [OpenAI Tokenizer](https://platform.openai.com/tokenizer)
- [Anthropic Token 计数](https://calculator.anthropic.com/)
- [Google Token 计数](https://gemini.google.com/token)

### 开源工具

- [tiktoken](https://github.com/openai/tiktoken) - OpenAI 分词器
- [tokenizers](https://github.com/huggingface/tokenizers) - Hugging Face 分词器

---

**文档更新时间：2025 年 12 月**

---

## Vibe Coding（直觉编程）


## 概述

**Vibe Coding**（直觉编程、感觉编程）是一种**依赖直觉、经验和即时反馈**的编程方式。开发者不严格遵循规范或计划，而是根据"感觉"来编写和调整代码。

> **核心理念**：跟着直觉走，快速迭代，边做边改

---

## 核心概念

### 1. 什么是 Vibe Coding

**Vibe Coding** 的特点：

- **无明确规划**：不写详细设计文档
- **快速迭代**：写代码 → 调整 → 再调整
- **依赖直觉**：凭"感觉"判断代码好坏
- **即时反馈**：边运行边修改
- **AI 辅助**：用 AI 快速探索想法

### 2. Vibe Coding vs 传统编程

| 维度 | 传统编程 | Vibe Coding |
| ---- | -------- | ----------- |
| **规划** | 详细设计 | 即兴发挥 |
| **文档** | 先写文档 | 代码即文档 |
| **流程** | 需求→设计→编码 | 想法→代码→调整 |
| **测试** | 先写测试 | 后补测试 |
| **灵活性** | 结构化 | 高度灵活 |

---

## Vibe Coding 的风格

### 1. 探索式编程

```
想法: "我想做一个简单的待办事项应用"
    ↓
快速原型: 用 AI 生成基础代码
    ↓
运行测试: 看看效果如何
    ↓
直觉调整: "这个颜色不好看，改一下"
    ↓
添加功能: "再加个分类功能"
    ↓
继续调整: "布局有点乱，重构一下"
```

### 2. 对话式编程

```
开发者: "帮我做个登录页面"
    AI: [生成代码]
开发者: "颜色太深了"
    AI: [调整颜色]
开发者: "加个忘记密码链接"
    AI: [添加功能]
开发者: "这个位置不对"
    AI: [调整布局]
...
```

### 3. 试错式编程

```
尝试1: [方案A] → 不行，太复杂
尝试2: [方案B] → 还是不对
尝试3: [方案C] → 感觉对了！
完善: [方案C改进] → 完成
```

---

## Vibe Coding 的场景

### 适合场景

| 场景 | 原因 |
| ---- | ---- |
| **原型开发** | 快速验证想法 |
| **创意项目** | 需要灵活探索 |
| **学习新技术** | 边做边学 |
| **个人项目** | 无需团队协作 |
| **黑客马拉松** | 时间有限，求快 |

### 不适合场景

| 场景 | 原因 |
| ---- | ---- |
| **大型团队项目** | 缺乏规范导致混乱 |
| **安全关键系统** | 需要严格验证 |
| **长期维护项目** | 技术债务积累 |
| **复杂业务系统** | 需要详细设计 |

---

## Vibe Coding + AI

### 1. AI 作为"直觉放大器"

```
开发者的直觉 → AI 快速实现 → 即时反馈 → 强化直觉
     ↑                                          ↓
     └────────────────────────────────────────┘
              持续迭代循环
```

### 2. 工具支持

| 工具 | Vibe Coding 支持 |
| ---- | --------------- |
| **Cursor** | 快速生成、即时修改 |
| **Claude Code** | 对话式开发 |
| **Cline** | VS Code 内的快速迭代 |
| **Replit** | 浏览器内即时运行 |

### 3. 典型工作流

```bash
# 1. 想到什么直接让 AI 做
claude-code "创建一个 React 待办组件"

# 2. 看着效果，凭直觉调整
claude-code "把按钮改成圆角，加个阴影"

# 3. 继续添加功能
claude-code "加个删除按钮，用红色"

# 4. 发现问题
claude-code "删除没反应，检查一下"

# 5. 重构调整
claude-code "代码有点乱，整理一下"
```

---

## Vibe Coding 的技巧

### 1. 快速原型

```
第一步: 5分钟实现核心功能
第二步: 运行看看效果
第三步: 凭直觉调整
第四步: 继续添加
第五步: 随时重构
```

### 2. 最小可行产品

```
不要一开始就想完整
先做最简单的能用的版本
然后逐步完善
```

### 3. 相信直觉

```
"感觉这个颜色不对" → 改
"感觉逻辑有点复杂" → 简化
"感觉这里可以优化" → 优化
```

### 4. 拥抱不完美

```
Vibe Coding 接受:
- 代码可能不够优雅
- 结构可能不够完美
- 测试可能不够完整
但重点是: 快速做出能用的东西
```

---

## Vibe Coding vs Spec-Driven Development

### 对比表

| 维度 | Vibe Coding | Spec-Driven Development |
| ---- | ----------- | ------------------------ |
| **规划** | 随性 | 严格 |
| **文档** | 代码即文档 | 详细规范 |
| **灵活性** | 极高 | 中等 |
| **可维护性** | 低 | 高 |
| **团队协作** | 困难 | 容易 |
| **学习曲线** | 低 | 高 |
| **AI 参与度** | 高 | 高 |
| **适用规模** | 小 | 大 |

### 何时使用

| 场景 | 推荐 |
| ---- | ---- |
| **创意验证** | Vibe Coding |
| **黑客马拉松** | Vibe Coding |
| **个人项目** | Vibe Coding |
| **团队项目** | Spec-Driven |
| **企业级系统** | Spec-Driven |
| **长期产品** | Spec-Driven |

---

## Vibe Coding 的最佳实践

### 1. 保持代码整洁

即使采用 Vibe Coding，也要：

```
- 定期重构
- 删除无用代码
- 保持一致的命名
- 添加必要注释
```

### 2. 使用 Git 分支

```
main (稳定版本)
  ↑
feature/experiment (随意尝试)
  ↓
  实验成功了 → 合并到 main
  实验失败了 → 直接删除
```

### 3. 设置时间限制

```
- 单次会话不超过 2 小时
- 避免陷入无休止的调整
- 定期回顾和整理
```

### 4. 记录重要决策

```
即使不写详细文档，也要记录:
- 为什么选择这个方案
- 遇到的坑和解决方案
- 下次改进的方向
```

---

## Vibe Coding 的风险

### 1. 技术债务

```
快速原型 → 技术债务积累
    ↓
如果不及时还债
    ↓
项目变得难以维护
```

### 2. 缺乏可追溯性

```
"为什么这样写?"
"我也不知道，当时感觉这样对"
```

### 3. 团队协作困难

```
"这个代码是什么意思?"
"我也不懂，是他凭感觉写的"
```

### 4. 难以复现

```
"这个功能怎么实现的?"
"忘记了，当时随便写的"
```

---

## 混合策略

### Vibe + Spec

最好的方式是**结合两者**：

```
┌─────────────────────────────────────────────────────────┐
│                 Vibe + Spec 混合策略                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  探索阶段 (Vibe)                                       │
│  ├── 快速原型                                           │
│  ├── 验证想法                                           │
│  └── 找到方向                                           │
│         ↓                                              │
│  稳定阶段 (Spec)                                       │
│  ├── 编写规范                                           │
│  ├── 重构代码                                           │
│  └── 添加测试                                           │
│         ↓                                              │
│  迭代循环                                               │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 实践建议

```
1. 个人项目: 多用 Vibe Coding
2. 团队项目: 核心用 Spec，边缘用 Vibe
3. 紧急需求: 先 Vibe 解决，后 Spec 规范
4. 创新探索: Vibe 先行，Spec 跟进
```

---

## 参考资源

### 相关概念

- [Spaghetti Code](https://en.wikipedia.org/wiki/Spaghetti_code) - 反面模式
- [Technical Debt](https://en.wikipedia.org/wiki/Technical_debt) - 技术债务
- [Prototype](https://en.wikipedia.org/wiki/Software_prototyping) - 原型开发

### 工具

- [Cursor](https://cursor.sh) - AI IDE
- [Claude Code](https://claude.ai/code) - AI CLI
- [Replit](https://replit.com) - 在线 IDE

---

**文档更新时间：2025 年 12 月**

---

## AI 生成小程序代码


## 提升效率

本页面为使用 AI 快速构建小程序的专题，希望能够帮助大家不断的提升自己的开发效率

同时也希望大家一起讨论参与，快速的生成他个成百上千个小程序, APP, 和网站！

## AI 学习中心：Skill 快速安装

如果你希望 AI 在你的业务项目中，按 `weapp-tailwindcss` 最佳实践快速完成小程序与多端接入，可以先安装 `weapp-tailwindcss` Skill：

```bash
npx skills add sonofmagic/skills --skill weapp-tailwindcss
```

该 Skill 除了接入配置与排障，也覆盖 Tailwind 写法规范（例如 `space-y-*` / `space-x-*` 在小程序端默认标签限制与修复优先级）。

详细说明见：[Skill（技能系统）](/docs/ai/basics/skill)

## 如何参与贡献

### 前置环境

1. `nodejs@22`
2. `pnpm@10`
3. `Github` 账号

### 开始

点击 [`fork weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss/fork), 然后 `git clone` 到本地在打开这个目录:

1. 执行 `pnpm i` 安装依赖
2. 执行 `pnpm build:pkg` 构建 `website` 的本地依赖包
3. 然后 `cd website && pnpm dev` (切换到 `website` 目录, 跑 `pnpm dev`，当然你也可以在 `vscode` 里面右键打开终端，然后 `pnpm dev` 运行)
4. 访问 `http://localhost:4000` 就是 `weapp-tailwindcss` 的官方文档网站了

然后，你可以在 `website/docs/ai` 目录下，新建 `md` / `mdx` 文件，进行写作，路由会自动映射到:

`http://localhost:4000/docs/ai/{your_doc_name}` 路径中去

> 比如你创建一个 `v0.md`，你的路由就是 `http://localhost:4000/docs/ai/v0`
>
> 假如你创建一个 `index.md`，比如这个页面就是一个 `index.md` 这个页面访问路径为 http://localhost:4000/docs/ai

假如你有素材，可以放在 `website/docs/ai/assets/{your_doc_name}` 目录下，然后在 `md` 文件中，进行引用

## 示例

### 网站

1. https://v0.dev/

2. https://docs.crewai.com/guides

3. https://bolt.new/

### 上传图片

比如要实现 `网页云音乐`，就手机上打开 `网页云音乐`，然后截长图，上传到 `v0.dev`

> 此处有截图

### 提示词

然后提示词为

- `技术栈为 uni-app vue3 tailwindcss, 实现这个页面`(根据你的需求自定义)

然后复制代码即可

> 此处有截图

---

## 国外顶尖编程模型选型建议书


> **核心结论**：在三大国外顶尖模型中，**Claude Opus 4.5** 在代码质量上保持领先，**GPT-5.2** 在数学推理上最强，**Gemini 3 Pro** 在多模态和长上下文场景表现突出。

## 执行摘要

经过对当前三大国外顶尖 AI 编程模型的深入分析，我们建议：

1. **代码质量优先**：采用 **Claude Opus 4.5**
   - 代码质量排名全球第 1
   - 代码理解和重构能力最强
   - 适合复杂系统架构设计
   - 代码审查和重构场景首选

2. **数学推理优先**：采用 **GPT-5.2**
   - AIME 2025 排名第 1（1.0 分，满分）
   - 算法和复杂数学问题最强
   - 适合算法竞赛、科学计算、量化交易
   - 逻辑推理能力领先

3. **多模态和长上下文**：采用 **Gemini 3 Pro**
   - 支持 200 万 token 超长上下文
   - 多模态能力最强（视频、音频、图片）
   - 适合处理大规模代码库和多媒体内容
   - Google 生态系统集成最佳

---

## 一、三大模型核心对比

### 1.1 基础信息对比

| 对比维度                 | Claude Opus 4.5   | GPT-5.2              | Gemini 3 Pro         |
| ------------------------ | ----------------- | -------------------- | -------------------- |
| **发布时间**             | 2025.11.24        | 2025.12.11           | 2025.12              |
| **开发商**               | Anthropic（美国） | OpenAI（美国）       | Google（美国）       |
| **代码能力排名**         | **第 1 名**       | 前 3 名              | 前 5 名              |
| **AIME 2025**            | 高分              | **第 1 名（1.0分）** | 高分                 |
| **最大上下文**           | 200K tokens       | 1M tokens            | **2M tokens**        |
| **多模态**               | 图片、音频        | 图片、音频           | **视频、音频、图片** |
| **价格（$/百万tokens）** | $5-25             | $1.75-14             | $1.25-10             |
| **开源状态**             | ❌ 闭源           | ❌ 闭源              | ❌ 闭源              |

**数据来源**：[LLM Stats](https://llm-stats.com/)、各模型官方文档、权威基准测试榜单

### 1.2 核心能力雷达图

```
代码生成能力
Claude Opus 4.5: ★★★★★ (代码质量第1)
GPT-5.2:       ★★★★★
Gemini 3 Pro:  ★★★★

数学推理能力
Claude Opus 4.5: ★★★★
GPT-5.2:       ★★★★★ (AIME满分)
Gemini 3 Pro:  ★★★★

长上下文处理
Claude Opus 4.5: ★★★
GPT-5.2:       ★★★★
Gemini 3 Pro:  ★★★★★ (200万tokens)

多模态能力
Claude Opus 4.5: ★★★
GPT-5.2:       ★★★
Gemini 3 Pro:  ★★★★★ (支持视频)

中文支持
Claude Opus 4.5: ★★★
GPT-5.2:       ★★★
Gemini 3 Pro:  ★★★

价格竞争力
Claude Opus 4.5: ★★ (最贵)
GPT-5.2:       ★★★
Gemini 3 Pro:  ★★★★ (较便宜)
```

---

## 二、Claude Opus 4.5：代码质量之王

### 2.1 为什么 Claude Opus 4.5 代码质量第一？

#### 权威排名

根据 [LLM Stats](https://llm-stats.com/) 最新数据：

- **代码质量排名：全球第 1 名**
- 综合排名前 5
- 在代码生成、代码理解、重构场景中表现最优

#### 核心优势

1. **代码理解能力**
   - 深度理解复杂代码结构
   - 准确识别代码异味和反模式
   - 跨文件依赖关系分析

2. **代码生成质量**
   - 生成代码可读性强
   - 遵循最佳实践和设计模式
   - 类型安全和错误处理完善

3. **重构能力**
   - 大规模代码重构
   - 架构演进建议
   - 技术债务识别和管理

4. **安全性意识**
   - 主动识别安全漏洞
   - 符合 OWASP 最佳实践
   - 输入验证和授权建议

### 2.2 适用场景

| 场景             | 适用度 | 说明                              |
| ---------------- | ------ | --------------------------------- |
| **代码审查**     | ★★★★★  | 能发现深层问题，提供重构建议      |
| **系统架构设计** | ★★★★★  | 理解复杂系统，提供架构方案        |
| **技术债务管理** | ★★★★★  | 识别技术债务，制定重构计划        |
| **算法实现**     | ★★★★   | 代码质量高，但数学推理略逊GPT-5.2 |
| **遗留系统迁移** | ★★★★★  | 深度理解旧代码，提供迁移方案      |
| **测试用例生成** | ★★★★★  | 覆盖边界情况，测试质量高          |
| **CI/CD 集成**   | ★★★★★  | Claude Code CLI 官方工具          |

### 2.3 Claude Code CLI：官方工程化工具

Claude Opus 4.5 配合 Claude Code CLI 提供完整的工程化能力：

```
Claude Code CLI
├── 官方维护（Anthropic）
├── 成熟的 Agent 架构
├── 150+ 插件生态
├── 项目级上下文管理
├── LSP 集成
└── 企业级最佳实践
```

**关键优势**：

- Anthropic 是 AI 安全和工程化规范的核心制定者
- 符合 ASL-3 安全标准
- 企业级合规框架
- 详见：[Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)

### 2.4 成本分析

#### 订阅价格与使用限制

| 版本      | 月费               | 额度刷新周期 | 使用额度 | 适用对象   |
| --------- | ------------------ | ------------ | -------- | ---------- |
| **Pro**   | $20（≈¥140）       | **每周**     | 基础额度 | 个人开发者 |
| **Teams** | $40/人/月（≈¥280） | **每周**     | 团队额度 | 小团队     |
| **Max**   | $200（≈¥1400）     | **每周**     | 大量额度 | 重度用户   |

> **重要说明（2025年8月28日起）**：
>
> - Anthropic 引入了新的**每周使用额度限制**
> - 额度每**7天**重置一次
> - Pro 和 Max 用户均有独立的每周使用上限
> - 超出额度后需等待下一周期或升级套餐
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（7天后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守服务条款）

#### API 按量计费

| 场景     | 输入             | 输出              |
| -------- | ---------------- | ----------------- |
| **标准** | $1-5/百万 tokens | $3-15/百万 tokens |

> **成本对比**：
>
> - Claude Opus 是三者中最贵的
> - 但代码质量最高，复杂场景下反而更经济（减少调试时间）
> - 代码审查和重构场景 ROI 最高

---

## 三、GPT-5.2：数学推理之王

### 3.1 为什么 GPT-5.2 数学推理最强？

#### 权威排名

根据 AIME 2025（美国数学邀请赛）：

- **AIME 2025 排名：第 1 名（1.0 分，满分）**
- 综合排名前 3
- 在数学、算法、逻辑推理场景中表现最优

#### 核心优势

1. **数学推理能力**
   - 复杂数学问题求解
   - 算法设计和优化
   - 数学证明生成
   - 量化策略分析

2. **逻辑推理**
   - 复杂条件判断
   - 多步骤推理链
   - 抽象问题建模
   - 逻辑漏洞识别

3. **算法能力**
   - 数据结构选择
   - 算法复杂度分析
   - 性能优化建议
   - 并发和并行计算

4. **科学计算**
   - 数值分析
   - 统计建模
   - 机器学习算法
   - 量子计算

### 3.2 适用场景

| 场景         | 适用度 | 说明                   |
| ------------ | ------ | ---------------------- |
| **算法竞赛** | ★★★★★  | 数学推理满分，算法最优 |
| **量化交易** | ★★★★★  | 复杂数学模型，策略回测 |
| **科学计算** | ★★★★★  | 数值分析，统计建模     |
| **机器学习** | ★★★★★  | 算法实现，模型优化     |
| **游戏 AI**  | ★★★★★  | 博弈论，策略优化       |
| **密码学**   | ★★★★★  | 数学基础，安全算法     |
| **性能优化** | ★★★★   | 算法复杂度分析         |

### 3.3 GPT-5.2-Codex-Max：代码专用版本

OpenAI 提供专门的代码模型：

```
GPT-5.2-Codex-Max
├── 专注代码生成
├── 代码补全能力
├── 多语言支持
└── 深度代码理解
```

**特点**：

- 代码能力与 GPT-5.2 相当
- 专为编程场景优化
- 适合集成到 IDE 和工具

### 3.4 成本分析

#### 订阅价格与使用限制

| 版本           | 月费               | 额度刷新周期 | 使用额度                                 | 适用对象   |
| -------------- | ------------------ | ------------ | ---------------------------------------- | ---------- |
| **Plus**       | $20（≈¥140）       | **每5小时**  | 30-150条消息/5小时                       | 个人开发者 |
| **Pro**        | $200（≈¥1400）     | **每5小时**  | 300-1500条本地消息或50-400个云任务/5小时 | 专业用户   |
| **Team**       | $30/人/月（≈¥210） | **每5小时**  | 团队共享额度                             | 团队       |
| **Enterprise** | 定制               | 灵活         | 定制                                     | 大企业     |

> **重要说明**：
>
> - **每5小时**刷新一次额度（滚动窗口）
> - Plus 用户还有**每周限制**（约6-7次完整会话后达到上限）
> - 超出额度后会提示 _"You've hit your usage limit. Upgrade to Pro or try again in X days Y hours"_
> - Codex CLI、Chat、Agent 模式、代码审查等功能消耗"premium requests"
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（5小时后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：升级到 Pro 版本获得更高额度
> - **方案四**：切换/注册其他订阅账号（需遵守服务条款）

#### API 按量计费

| 场景     | 输入                | 输出                |
| -------- | ------------------- | ------------------- |
| **标准** | $0.25-2/百万 tokens | $0.75-6/百万 tokens |

> **成本对比**：
>
> - GPT-5.2 价格中等，介于 Claude 和 Gemini 之间
> - 数学推理场景性价比最高
> - 适合算法密集型应用

---

## 四、Gemini 3 Pro：长上下文和多模态之王

### 4.1 为什么 Gemini 3 Pro 在长上下文和多模态领先？

#### 核心优势

1. **超长上下文**
   - **200 万 tokens**（三者中最长）
   - 可处理整个大型代码库
   - 跨文件深度关联分析
   - 长文档理解能力

2. **多模态能力**
   - **视频理解**（独有）
   - 音频处理
   - 图片分析
   - 多模态综合推理

3. **Google 生态集成**
   - Google Cloud 集成
   - Android 开发支持
   - TensorFlow/ML 集成
   - Google Workspace 协作

### 4.2 适用场景

| 场景             | 适用度 | 说明                      |
| ---------------- | ------ | ------------------------- |
| **大规模代码库** | ★★★★★  | 200万tokens，一次分析全库 |
| **视频内容分析** | ★★★★★  | 独有视频理解能力          |
| **多模态应用**   | ★★★★★  | 图文音视频综合处理        |
| **Android 开发** | ★★★★★  | Google 官方支持           |
| **长文档处理**   | ★★★★★  | 超长文档理解              |
| **知识库构建**   | ★★★★★  | 大规模资料整合            |
| **代码迁移**     | ★★★★   | 全库分析，迁移方案        |

### 4.3 Gemini 2.0 Flash：速度优先版本

Google 提供轻量级版本：

```
Gemini 2.0 Flash
├── 响应速度快
├── 成本更低
├── 适合简单任务
└── 实时交互场景
```

### 4.4 成本分析

#### Gemini Code Assist 订阅价格

| 版本           | 月费         | 刷新周期 | 使用额度           | 适用对象   |
| -------------- | ------------ | -------- | ------------------ | ---------- |
| **Standard**   | $19（≈¥130） | **每日** | 无限代码补全       | 个人开发者 |
| **Enterprise** | $45（≈¥310） | **每日** | 100个PR reviews/天 | 企业团队   |

> **使用限制说明**：
>
> - **代码补全**：Standard 和 Enterprise 均为无限次
> - **Pull Request 审查**：Enterprise 100次/天，Consumer 版本 33次/天
> - **Flash Free Tier**：1500 requests/天（Flash 和 Flash-Lite 共享）
> - **Gemini 3 Pro Preview**：250 messages/24小时
> - **Gemini 3.0 Ultra**：20 requests/天（2025年从250次大幅削减92%）
> - **Main Gemini App**：100 queries/天限制
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（1天后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：升级到 Enterprise 版本获得更高额度
> - **方案四**：切换/注册其他订阅账号（需遵守服务条款）

#### API 按量计费

| 场景     | 输入                    | 输出                    |
| -------- | ----------------------- | ----------------------- |
| **标准** | $0.125-1.25/百万 tokens | $0.375-3.75/百万 tokens |

> **成本对比**：
>
> - Gemini 3 Pro 是三者中最便宜的
> - 长上下文场景性价比最高
> - 适合大规模代码库分析

---

## 五、三大模型深度对比

### 5.1 编程能力对比

| 能力维度         | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| ---------------- | --------------- | ------- | ------------ |
| **代码生成质量** | ★★★★★           | ★★★★★   | ★★★★         |
| **代码理解**     | ★★★★★           | ★★★★    | ★★★★         |
| **代码重构**     | ★★★★★           | ★★★★    | ★★★          |
| **调试能力**     | ★★★★★           | ★★★★    | ★★★          |
| **测试用例生成** | ★★★★★           | ★★★★    | ★★★          |
| **文档生成**     | ★★★★★           | ★★★★    | ★★★★         |
| **架构设计**     | ★★★★★           | ★★★★    | ★★★          |

**结论**：

- **代码质量**：Claude Opus 4.5 全面领先
- **代码生成**：Claude 和 GPT-5.2 相当
- **文档生成**：三者都较强

### 5.2 推理能力对比

| 能力维度       | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| -------------- | --------------- | ------- | ------------ |
| **数学推理**   | ★★★★            | ★★★★★   | ★★★★         |
| **逻辑推理**   | ★★★★★           | ★★★★★   | ★★★★         |
| **算法设计**   | ★★★★            | ★★★★★   | ★★★★         |
| **抽象思维**   | ★★★★★           | ★★★★★   | ★★★★         |
| **多步骤推理** | ★★★★★           | ★★★★★   | ★★★★         |
| **创造性思维** | ★★★★★           | ★★★★    | ★★★★         |

**结论**：

- **数学推理**：GPT-5.2 一骑绝尘（AIME满分）
- **逻辑推理**：Claude 和 GPT-5.2 相当
- **创造性**：Claude 略强

### 5.3 工程化能力对比

| 能力维度       | Claude Opus 4.5 | GPT-5.2  | Gemini 3 Pro |
| -------------- | --------------- | -------- | ------------ |
| **CLI 工具**   | ✅ Claude Code  | ⭐⭐⭐   | ⭐⭐⭐       |
| **IDE 集成**   | ⭐⭐⭐⭐⭐      | ⭐⭐⭐⭐ | ⭐⭐⭐⭐     |
| **插件生态**   | 150+ 插件       | ⭐⭐⭐   | ⭐⭐⭐       |
| **企业支持**   | ★★★★★           | ★★★★★    | ★★★★★        |
| **API 稳定性** | ★★★★★           | ★★★★★    | ★★★★★        |
| **文档质量**   | ★★★★★           | ★★★★     | ★★★★         |

**结论**：

- **工程化**：Claude Code CLI 生态最完善
- **IDE 集成**：三者都有良好支持
- **企业支持**：三家都有企业版

### 5.4 价格对比

| 价格维度         | Claude Opus 4.5   | GPT-5.2     | Gemini 3 Pro   |
| ---------------- | ----------------- | ----------- | -------------- |
| **订阅费**       | $20-200           | $20-200     | $19-45         |
| **API 输入**     | $1-5/M            | $0.25-2/M   | $0.125-1.25/M  |
| **API 输出**     | $3-15/M           | $0.75-6/M   | $0.375-3.75/M  |
| **额度刷新周期** | **每7天（每周）** | **每5小时** | **每日**       |
| **价格竞争力**   | ★★（最贵）        | ★★★         | ★★★★（最便宜） |

**结论**：

- **最便宜**：Gemini 3 Pro
- **最贵**：Claude Opus 4.5
- **额度刷新频率**：GPT-5.2 最高（5小时），Gemini 次之（每日），Claude 最低（每周）
- **性价比**：需结合使用场景判断

### 5.5 特色功能对比

| 特色功能        | Claude Opus 4.5 | GPT-5.2    | Gemini 3 Pro         |
| --------------- | --------------- | ---------- | -------------------- |
| **超长上下文**  | 200K            | 1M         | **2M**               |
| **视频理解**    | ❌              | ❌         | ✅                   |
| **代码审查**    | ★★★★★           | ★★★★       | ★★★                  |
| **多模态**      | 图片、音频      | 图片、音频 | **视频、音频、图片** |
| **AIME 满分**   | ❌              | ✅         | ❌                   |
| **代码质量第1** | ✅              | ❌         | ❌                   |

---

## 六、场景化选型建议

### 6.1 按应用场景选型

#### 代码质量和重构场景

**推荐：Claude Opus 4.5**

| 场景         | 推荐模型        | 原因                         |
| ------------ | --------------- | ---------------------------- |
| 代码审查     | Claude Opus 4.5 | 代码质量第1，识别深层问题    |
| 遗留系统重构 | Claude Opus 4.5 | 深度理解旧代码，提供演进方案 |
| 技术债务管理 | Claude Opus 4.5 | 识别技术债务，制定重构计划   |
| 架构设计     | Claude Opus 4.5 | 系统级架构建议               |
| 测试用例生成 | Claude Opus 4.5 | 覆盖边界情况，质量高         |

#### 数学和算法场景

**推荐：GPT-5.2**

| 场景     | 推荐模型 | 原因                   |
| -------- | -------- | ---------------------- |
| 算法竞赛 | GPT-5.2  | AIME满分，数学推理最强 |
| 量化交易 | GPT-5.2  | 复杂数学模型，策略优化 |
| 科学计算 | GPT-5.2  | 数值分析，统计建模     |
| 机器学习 | GPT-5.2  | 算法实现，模型优化     |
| 游戏 AI  | GPT-5.2  | 博弈论，策略优化       |

#### 大规模代码库和多模态场景

**推荐：Gemini 3 Pro**

| 场景             | 推荐模型     | 原因                  |
| ---------------- | ------------ | --------------------- |
| 大规模代码库分析 | Gemini 3 Pro | 200万tokens，一次全库 |
| 视频内容理解     | Gemini 3 Pro | 独有视频理解能力      |
| Android 开发     | Gemini 3 Pro | Google 官方支持       |
| 长文档处理       | Gemini 3 Pro | 超长上下文            |
| 多模态应用       | Gemini 3 Pro | 图文音视频综合        |

### 6.2 按团队规模选型

#### 个人开发者

| 预算     | 推荐方案            | 月费  |
| -------- | ------------------- | ----- |
| $30 以内 | Gemini 3 Pro API    | $7-21 |
| $30-70   | GPT-5.2 Plus        | $20   |
| $70-210  | Claude Opus 4.5 Pro | $200  |

#### 小团队（2-5人）

| 预算      | 推荐方案             | 月费     |
| --------- | -------------------- | -------- |
| $140-420  | Gemini 3 Pro API     | $70-280  |
| $420-850  | GPT-5.2 Team         | $150     |
| $850-1400 | Claude Opus 4.5 Team | $200-400 |

#### 中大团队（20+人）

| 预算      | 推荐方案 | 说明               |
| --------- | -------- | ------------------ |
| $2800+/月 | 混合策略 | 不同场景用不同模型 |
| $7000+/月 | 企业定制 | 三家都支持企业定制 |

---

## 七、混合策略：多模型协同

### 7.1 为什么需要多模型？

不同模型有不同优势，混合使用可以达到最佳效果：

```
多模型协同策略
├── Claude Opus 4.5：代码质量把关
├── GPT-5.2：算法和数学问题
├── Gemini 3 Pro：大规模代码库分析
└── 成本优化：根据任务选模型
```

### 7.2 混合策略示例

#### 开发流程中的模型分配

| 开发阶段     | 推荐模型        | 理由               |
| ------------ | --------------- | ------------------ |
| **需求分析** | Claude Opus 4.5 | 深度理解，架构设计 |
| **算法设计** | GPT-5.2         | 数学推理最强       |
| **代码实现** | Claude Opus 4.5 | 代码质量最高       |
| **代码审查** | Claude Opus 4.5 | 识别深层问题       |
| **性能优化** | GPT-5.2         | 算法复杂度分析     |
| **全库分析** | Gemini 3 Pro    | 超长上下文         |
| **测试用例** | Claude Opus 4.5 | 覆盖全面           |
| **文档生成** | Gemini 3 Pro    | 长文档处理         |

### 7.3 成本优化策略

#### 按任务复杂度选模型

| 复杂度       | 推荐模型        | 理由         |
| ------------ | --------------- | ------------ |
| **简单任务** | Gemini 3 Pro    | 最便宜，够用 |
| **中等任务** | GPT-5.2         | 性价比高     |
| **复杂任务** | Claude Opus 4.5 | 质量优先     |

#### 成本对比示例

假设每月处理 1000 个任务：

| 策略             | 月费 | Token成本 | 总成本 |
| ---------------- | ---- | --------- | ------ |
| **全用 Claude**  | $200 | $2800     | $3000  |
| **全用 GPT-5.2** | $200 | $1100     | $1300  |
| **全用 Gemini**  | $0   | $550      | $550   |
| **混合策略**     | $200 | $850      | $1050  |

**结论**：混合策略可以节省 **65%** 成本，同时保持高质量。

---

## 八、工程化工具对比

### 8.1 CLI 工具对比

| 工具           | Claude Code | OpenAI CLI | Gemini CLI |
| -------------- | ----------- | ---------- | ---------- |
| **官方支持**   | ✅          | ⭐⭐⭐     | ⭐⭐⭐     |
| **Agent 能力** | ★★★★★       | ★★★        | ★★★        |
| **插件生态**   | 150+        | ⭐⭐       | ⭐⭐       |
| **项目上下文** | ★★★★★       | ★★★★       | ★★★★       |
| **多模型支持** | ⭐⭐        | ⭐⭐       | ⭐⭐       |

**结论**：Claude Code CLI 是最完善的工程化工具。

### 8.2 IDE 集成对比

| IDE                | Claude  | GPT | Gemini |
| ------------------ | ------- | --- | ------ |
| **VS Code**        | ✅      | ✅  | ✅     |
| **JetBrains**      | ✅      | ✅  | ✅     |
| **Cursor**         | ✅ 原生 | ✅  | ⭐⭐   |
| **GitHub Copilot** | ⭐⭐    | ✅  | ⭐⭐   |

**结论**：三家都有良好 IDE 支持，Cursor 对 Claude 支持最好。

---

## 九、实施建议

### 9.1 推荐方案总结

```
┌─────────────────────────────────────────────────────────┐
│              国外顶尖模型选型方案                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  代码质量优先：Claude Opus 4.5                          │
│  ├── 代码质量全球第1                                    │
│  ├── 代码审查和重构最强                                 │
│  ├── Claude Code CLI 工程化完善                         │
│  └── 适合：代码审查、架构设计、技术债务管理              │
│                                                         │
│  数学推理优先：GPT-5.2                                  │
│  ├── AIME 2025 满分（第1名）                            │
│  ├── 算法和科学计算最强                                 │
│  └── 适合：算法竞赛、量化交易、机器学习                  │
│                                                         │
│  长上下文优先：Gemini 3 Pro                             │
│  ├── 200万tokens 超长上下文                             │
│  ├── 多模态能力最强（支持视频）                          │
│  └── 适合：大规模代码库、视频理解、Android 开发          │
│                                                         │
│  混合策略：根据任务选择最优模型                          │
│  ├── 简单任务 → Gemini 3 Pro（最便宜）                  │
│  ├── 代码质量 → Claude Opus 4.5（最强）                 │
│  ├── 数学推理 → GPT-5.2（最强）                         │
│  └── 成本优化：节省65%+                                 │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 9.2 分阶段实施

#### 第一阶段：单一模型试点（1-2周）

| 步骤 | 内容                            | 目标     |
| ---- | ------------------------------- | -------- |
| 1    | 选择一个主力模型（建议 Claude） | 验证效果 |
| 2    | 小范围试点（2-3人）             | 收集反馈 |
| 3    | 评估成本和效果                  | 决策方案 |

#### 第二阶段：混合策略（1-2个月）

| 步骤 | 内容                   | 覆盖范围 |
| ---- | ---------------------- | -------- |
| 1    | 根据任务类型选择模型   | 全团队   |
| 2    | 建立使用规范和最佳实践 | 文档化   |
| 3    | 成本监控和优化         | 持续     |

#### 第三阶段：全面应用（持续）

| 步骤 | 内容             | 目标     |
| ---- | ---------------- | -------- |
| 1    | 多模型协同工作流 | 自动化   |
| 2    | 企业级部署       | 规模化   |
| 3    | 持续评估新模型   | 保持领先 |

---

## 十、成本效益分析

### 10.1 投资回报率（ROI）

假设 10 人团队，平均年薪 $15 万：

| 方案                | 月度成本 | 年度成本 | 效率提升 | 年度价值 | ROI       |
| ------------------- | -------- | -------- | -------- | -------- | --------- |
| **Claude Opus 4.5** | $1700    | $20400   | 30%      | $450000  | **2205%** |
| **GPT-5.2**         | $1150    | $13800   | 25%      | $375000  | **2717%** |
| **Gemini 3 Pro**    | $700     | $8400    | 20%      | $300000  | **3571%** |
| **混合策略**        | $1050    | $12600   | 30%      | $450000  | **3571%** |

**结论**：混合策略 ROI 最高。

### 10.2 真实成本对比

#### 10 人团队，月预算 $1400

**纯 Claude 方案**：

- Claude Teams：$40 × 10 = $400
- Claude API：$857
- 可用 tokens：约 350 万/月
- **总计：$1257/月**

**混合策略**：

- Claude Teams：$400（代码审查）
- GPT-5.2 API：$285（算法）
- Gemini API：$215（全库分析）
- **总计：$900/月，节省 28%**

---

## 十一、风险与挑战

### 11.1 潜在风险

| 风险           | 影响 | 缓解措施               |
| -------------- | ---- | ---------------------- |
| **供应商锁定** | 高   | 多模型策略，保持灵活性 |
| **成本超支**   | 中   | 预算告警，成本监控     |
| **模型变化**   | 中   | 持续评估，快速适配     |
| **数据安全**   | 高   | 企业版，私有化部署     |

### 11.2 应对策略

1. **多模型策略**：降低供应商锁定风险
2. **成本监控**：设置预算告警
3. **持续评估**：关注新模型发布
4. **数据安全**：选择企业版或私有化部署

---

## 十二、总结与建议

### 12.1 核心结论

> **三大国外顶尖模型各有优势，推荐混合策略**

- **Claude Opus 4.5**：代码质量第1，适合代码审查和重构
- **GPT-5.2**：数学推理满分，适合算法和科学计算
- **Gemini 3 Pro**：200万tokens，适合大规模代码库
- **混合策略**：节省65%成本，同时保持高质量

### 12.2 关键论点

1. **代码质量**：Claude Opus 4.5 全球第1
2. **数学推理**：GPT-5.2 AIME满分
3. **长上下文**：Gemini 3 Pro 200万tokens
4. **工程化**：Claude Code CLI 最完善
5. **成本**：Gemini最便宜，Claude最贵
6. **混合策略**：性价比最高

### 12.3 预期收益

| 收益类型     | Claude     | GPT-5.2    | Gemini     | 混合策略   |
| ------------ | ---------- | ---------- | ---------- | ---------- |
| **代码质量** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ |
| **数学推理** | ⭐⭐⭐⭐   | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐   | ⭐⭐⭐⭐⭐ |
| **长上下文** | ⭐⭐⭐     | ⭐⭐⭐⭐   | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **月费**     | $200       | $200       | $0         | $200       |
| **API成本**  | 高         | 中         | 低         | 中低       |
| **ROI**      | 2205%      | 2717%      | 3571%      | **3571%**  |

---

## 十三、参考来源

### 官方网站

- [Claude Code](https://claude.ai/code)
- [Claude Opus 4.5 发布公告](https://www.anthropic.com/news/claude-opus-4-5)
- [OpenAI 官网](https://openai.com/)
- [GPT-5.2 发布](https://openai.com/index/introducing-gpt-5-2-codex/)
- [Google Gemini](https://gemini.google.com/)
- [Gemini 3 Pro 发布](https://blog.google/technology/ai/google-gemini-pro-update-122025/)

### 权威榜单

- [LLM Stats - 全球模型排名](https://llm-stats.com/)
- [AIME 2025 美国数学邀请赛](https://aime.mathhub.org/)
- [HumanEval 代码生成基准](https://github.com/openai/human-eval)

### 价格与成本

- [Claude Code 付费完全指南](https://www.cursor-ide.com/blog/claude-code-pricing)
- [OpenAI 定价](https://openai.com/pricing)
- [Google Gemini 定价](https://cloud.google.com/vertex-ai/generative-ai/pricing)

### 产品对比

- [Claude vs GPT vs Gemini - 2025 对比](https://www.anthropic.com/news/claude-opus-4-5)
- [2025 年顶尖 AI 模型深度评测](https://aicoding.csdn.net/686e3291080e555a88ce5407.html)

### 技术文档

- [Claude Code CLI 文档](https://docs.anthropic.com/claude-code)
- [OpenAI API 文档](https://platform.openai.com/docs/)
- [Gemini API 文档](https://cloud.google.com/vertex-ai/generative-ai/docs)

---

**文档更新时间：2025 年 12 月**

**注意**：

1. 价格信息可能随时变动，请以官方公布为准
2. AI 模型的能力排名基于公开基准测试，实际效果可能因使用场景而异
3. 混合策略需要工程化支持，建议从试点开始
4. 企业用户建议选择企业版或私有化部署以保障数据安全

---

## LLM 友好文档 (llms.txt)


## 生成方式

1. 在仓库根目录执行 `pnpm --filter @weapp-tailwindcss/website build`（或 `cd website && pnpm build`）。
2. 构建后，`website/build/` 会生成：
   - `llms.txt`（索引）
   - `llms-full.txt`（完整内容）
   - `llms-quickstart.txt`（上手/AI 工作流）
   - `llms-api.txt`（配置、API、迁移与问题）
   - 去除 MDX import 的纯 Markdown 文件，方便直接喂给模型。

## 线上地址

- `https://tw.icebreaker.top/llms.txt`
- `https://tw.icebreaker.top/llms-full.txt`
- `https://tw.icebreaker.top/llms-quickstart.txt`
- `https://tw.icebreaker.top/llms-api.txt`

> 如果通过 GitHub Pages 访问，请注意前缀路径 `/weapp-tailwindcss/`。

## 给 AI 的示例提示词

> 你可以从 https://tw.icebreaker.top/llms-quickstart.txt 和 https://tw.icebreaker.top/llms-api.txt 读取 weapp-tailwindcss 的入门与配置说明，回答时请引用相关链接。

## 离线使用

- 下载 `llms-full.txt` 直接给模型。
- 或将生成阶段的 Markdown 文件整体打包后供模型上下文检索。

---

## AI 编程工具选型建议书


> **核心结论**：推荐以 **GLM-4.7** 为核心模型，配合 **Claude Code CLI** 构建 AI 工程化能力。

## 执行摘要

经过对当前主流 AI 编程工具和模型的深入分析，我们建议：

1. **模型选择**：采用 **GLM-4.7** 作为主力模型
   - 原则：用新不用旧，GLM-4.7 是智谱 2025 年 12 月最新旗舰
   - 能力：代码能力超越 GPT-5（官方宣称），总参数 358B
   - 性价比：价格为 Claude Opus 的 1/7 - 1/12
   - 世界排名第 6，是国产开源模型中排名最高

2. **工程化能力**：使用 **Claude Code CLI + GLM-4.7** 组合
   - **GLM-4.7 月费**：¥40-400（远低于 Claude 的 $20-200）
   - 可直接配置使用 GLM-4.7 作为底层模型
   - 成熟的 Agent 架构和工具生态
   - 项目级上下文管理能力
   - **Token 成本仅为原生 Claude 的 12%**
   - **CLI 比编辑器插件更强大、更灵活、更工程化**

3. **插件生态系统**：Claude Code CLI 拥有完整的工程化插件体系
   - **PR Review Toolkit**：自动化代码审查（测试、错误处理、类型设计、代码质量）
   - **Development Workflows**：Python、JavaScript/TypeScript、Backend、Frontend 专业工作流
   - **Document Skills**：Excel、Word、PowerPoint、PDF 文档处理
   - **Code Quality Tools**：代码重构、技术债务管理、架构审查
   - **Enterprise Plugins**：150+ 命令、74+ 专业代理、GitHub 集成
   - 详见：[Claude Plugins Marketplace](https://claude-plugins.dev/)

4. **工具选择**：推荐以 **CLI 为主力工具**
   - CLI 具有更完整的工具链和更强大的 Agent 能力
   - 不依赖特定 IDE，可在任何环境使用
   - 更适合处理复杂的、多步骤的任务
   - 鼓励开发者体验 Cursor、Qoder 等 IDE 了解前沿技术，但不建议作为主力工具

---

## 一、为什么选择 GLM-4.7？

### 1.0 模型质量的重要性

在深入对比之前，必须明确一个核心观点：**模型质量是 AI 辅助编程的决定性因素**。

#### 为什么模型好坏如此关键？

1. **垃圾模型 = 纯纯浪费**
   - 无论如何优化 prompt、如何调整交互方式
   - 无法理解复杂需求 → 生成错误代码 → 浪费调试时间
   - 无法理解项目上下文 → 需要反复解释 → 浪费沟通成本
   - 无法生成可用代码 → 需要人工重写 → 浪费开发时间

2. **好模型 = 效率倍增**
   - 准确理解需求 → 一次生成可用代码
   - 深度理解上下文 → 减少重复解释
   - 代码质量高 → 调试成本低

3. **成本陷阱**
   - 使用便宜但能力差的模型 → 需要多次尝试 → 实际成本更高
   - 使用能力强的模型 → 一次成功 → 总成本更低

> **核心结论**：在 AI 辅助编程中，**模型质量 > 工具功能 > 交互技巧**。使用垃圾模型，再好的工具和交互技巧都是徒劳。

#### 真实案例对比

假设完成一个中等复杂度的需求（CRUD + 业务逻辑）：

| 模型质量                            | 交互次数 | 总耗时   | 成功率 | 结论     |
| ----------------------------------- | -------- | -------- | ------ | -------- |
| **顶级模型**（Claude Opus/GLM-4.7） | 2-3 次   | 2-4 小时 | 85-95% | 高效完成 |
| **中等模型**                        | 5-8 次   | 1-2 天   | 60-75% | 勉强可用 |
| **垃圾模型**                        | 10+ 次   | 3-5 天   | 30-50% | 纯纯浪费 |

> **结论**：使用顶级模型虽然单价高，但总耗时和总成本反而更低。

### 1.1 用新不用旧：模型迭代的核心原则

| 对比维度                  | GLM-4.7         | GLM-4.6    | Claude Opus 4.5   | GPT 5.2        | GPT 5.1-codex-max |
| ------------------------- | --------------- | ---------- | ----------------- | -------------- | ----------------- |
| **发布时间**              | 2025.12.22      | 2025.09.30 | 2025.11.24        | 2025.12.11     | 2025.11.19        |
| **代码能力**              | 最强            | 较强       | 最强              | 最强           | 最强              |
| **世界排名**              | **第 6 名**     | 第 7 名    | 第 2 名           | 第 3 名        | -                 |
| **价格（¥/百万 tokens）** | ¥0.6-2.2        | ¥0.6-2.2   | ¥5-25             | ¥1.75-14       | ¥1.25-10          |
| **所属机构**              | 智谱AI（中国）  | 智谱AI     | Anthropic（美国） | OpenAI（美国） | OpenAI（美国）    |
| **时效性**                | ⭐⭐⭐⭐⭐ 最新 | ⭐⭐⭐⭐   | ⭐⭐⭐⭐⭐        | ⭐⭐⭐⭐⭐     | ⭐⭐⭐⭐⭐        |

**星级说明**：⭐ 越多代表越新、技术越先进（均为 2025 年最新一代模型）

**数据来源**：[LLM Stats](https://llm-stats.com/)、各模型官方文档、权威基准测试榜单

> **权威排名**：根据 [LLM Stats](https://llm-stats.com/) 最新数据（2025.12.23）：
>
> - **GLM-4.7**：世界**第 6 名**，是国产开源模型中排名最高
> - **GLM-4.6**：世界第 7 名，621 分
> - **Claude Opus 4.5**：代码质量排名第 1，综合排名前 5
> - **GPT 5.2**：综合排名前 3，AIME 2025 排名第 1（1.0 分）

> **Qoder 模型说明**：Qoder 采用**多模型后端智能路由策略**，根据任务类型自动选择最合适的模型：
>
> - **Claude 系列**：擅长代码理解和重构
> - **GPT 系列**：代码生成能力强
> - **Gemini 系列**：多模态能力优秀
> - **通义千问系列**：阿里自研模型
>
> Qoder 提供**模型分级选择器**（Model Tier Selector），支持四个层级：
>
> - **智能路由**：自适应算法自动选择最合适模型（推荐默认）
> - **极致性能**：使用最优可用模型
> - **经济高效**：高性价比模型选择
> - **基础轻量**：基础模型服务（免费）
>
> 来源：
>
> - [Qoder 官方文档 - 模型分级选择器](https://docs.qoder.com/zh/user-guide/chat/model-tier-selector)
> - [Jimmy Song - Qoder 深度评测](https://jimmysong.io/zh/blog/qoder-alibaba-ai-ide-personal-review/)

**核心论点**：

- GLM-4.7 是智谱最新旗舰（2025年12月22日发布），面向 Agentic Coding 场景强化
- 世界排名第 6（来源：[LLM Stats](https://llm-stats.com/)），在多项编程基准测试中取得开源模型领先表现
- 代码能力超越 GPT-5（官方宣称），与 Claude Opus 4.5、GPT 5.2 同属 2025 年最新一代
- 价格仅为 Claude Opus 的 1/7 左右，成本优势显著
- 总参数 358B，是目前参数量最大的开源模型之一
- MIT 开源协议，可自由使用和修改
- **用新不用旧**：GLM-4.7 是 2025 年 12 月最新发布

### 1.2 GLM-4.7 核心优势

#### 技术优势

```
代码能力
├── Agentic Coding 场景强化
├── 长程任务规划能力
├── 工具协同能力
└── 前端美感（Artifacts）

通用能力
├── 回复简洁自然
├── 写作沉浸感强
└── 指令遵循更强
```

#### 性能表现

- **代码能力**：宣称超越 GPT-5
- **开源表现**：多项基准测试 SOTA
- **工具支持**：原生支持 Claude Code、Cline 等主流工具

#### 成本优势

| 模型                | 输入价格 | 输出价格 | 价格比 |
| ------------------- | -------- | -------- | ------ |
| **GLM-4.7**         | ¥0.6-2.2 | ¥2.2-6.6 | 1x     |
| **Claude Opus 4.5** | ¥5-25    | ¥15-75   | 7-12x  |
| **GPT 5.2**         | ¥1.75-14 | ¥5.25-42 | 3-7x   |

> **成本对比**：相同任务量，GLM-4.7 成本约为 Claude Opus 的 **12%**，GPT 5.2 的 **30%**

---

## 二、GLM-4.7 + Claude Code CLI：最佳工程化组合

### 2.1 为什么选择 Claude Code CLI？

#### 核心价值：AI 工程化基础设施

```
Claude Code CLI
├── 成熟的 Agent 架构
│   ├── 子代理机制（Task 工具）
│   ├── 工具调用能力
│   └── 上下文管理
├── 完整的工具生态
│   ├── Read/Write/Edit 文件操作
│   ├── Bash 命令执行
│   ├── Grep 搜索
│   └── LSP 集成
└── 项目级能力
    ├── CLAUDE.md 配置
    ├── 全局上下文理解
    └── 多文件协作
```

#### 关键特性：可配置使用 GLM-4.7

Claude Code CLI 支持自定义模型配置，可以直接将 GLM-4.7 作为底层模型：

1. **GLM-4.7 提供**：最新的代码能力和推理能力
2. **Claude Code 提供**：成熟的工程化框架和工具链
3. **组合效果**：最新模型 + 成熟架构 = 最佳工程化方案
4. **低成本订阅**：GLM-4.7 Coding Plan 月费仅 ¥40-400

> **重要优势**：使用 Claude Code CLI + GLM-4.7 组合：
>
> - **GLM-4.7 订阅费**：¥40-400/月（远低于 Claude 的 $20-200 ≈ ¥140-1400）
> - **Token 成本**：¥0.6-2.2/百万 tokens（Claude 的 12%）
> - **Claude Code CLI**：免费安装使用

### 2.2 与其他方案对比

| 方案                          | 模型                | 工程化能力 | 月费                   | Token/点数成本            | 推荐度     |
| ----------------------------- | ------------------- | ---------- | ---------------------- | ------------------------- | ---------- |
| **GLM-4.7 + Claude Code CLI** | GLM-4.7（世界第 6） | 成熟       | **¥40-400**            | ¥0.6-2.2/M                | ⭐⭐⭐⭐⭐ |
| **Qoder**                     | 多模型智能路由      | 较新       | $20-60 (约 ¥140-420)   | 2000-6000 点数/月         | ⭐⭐⭐⭐   |
| Claude Code                   | Claude Opus 4.5     | 成熟       | $20-200 (约 ¥140-1400) | $1-5/M (约 ¥7-35/M)       | ⭐⭐⭐⭐   |
| Cursor                        | Claude/GPT 5.2      | IDE 集成   | $20-200 (约 ¥140-1400) | $0.25-2/M (约 ¥1.75-14/M) | ⭐⭐⭐⭐   |

**结论**：GLM-4.7 + Claude Code CLI 在**模型时效性**、**工程化能力**、**成本**三方面都达到最优。

> **成本对比**（月费 + Token）：
>
> - **GLM-4.7 + Claude Code CLI**：¥40-400 + ¥0.6-2.2/百万 tokens
> - **Qoder**：Pro $20 (约 ¥140)、Pro+ $60 (约 ¥420)，包含 2000-6000 点数/月
> - **Claude Code 原生**：$20-200 (约 ¥140-1400) + $1-5/M (约 ¥7-35/百万 tokens)
> - **Cursor**：$20-200 (约 ¥140-1400) + $0.25-2/M (约 ¥1.75-14/百万 tokens)
>
> **优势**：
>
> - GLM-4.7 月费仅为 Qoder 的 **29-295%**（取决于版本）
> - GLM-4.7 月费仅为 Claude 的 **29-295%**
> - Token 成本仅为 Claude 的 **12%**
> - 世界排名第 6，代码能力最强

---

## 三、产品对比分析

### 3.1 IDE 对比：Qoder vs Cursor

#### 核心功能对比表

| 功能类别       | 功能            | Qoder          | Cursor       | 说明                                                                                                     |
| -------------- | --------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| **基础架构**   | 基于 VS Code    | ✅             | ✅           | 两者都基于 VS Code                                                                                       |
| **插件支持**   | VS Code 插件    | ✅             | ✅           | 完全兼容 VS Code 生态                                                                                    |
| **代码补全**   | Tab 自动补全    | ⭐⭐⭐         | ⭐⭐⭐⭐⭐   | Cursor 更流畅，类似 Copilot                                                                              |
|                | 多行编辑        | ✅             | ✅           | Cursor 更成熟                                                                                            |
|                | 智能重写        | ✅             | ✅           | Cursor 体验更好                                                                                          |
|                | 光标预测        | ❌             | ✅           | Cursor 独有                                                                                              |
| **AI 聊天**    | Chat 对话       | ✅             | ✅           | 两者都有                                                                                                 |
|                | 代码库问答      | ✅             | ✅           | 都支持                                                                                                   |
|                | @符号引用代码   | ✅             | ✅           | 都支持                                                                                                   |
|                | 图片输入        | ❌             | ✅           | Cursor 独有                                                                                              |
|                | 网络搜索        | ❌             | ✅           | Cursor 的 @Web 功能                                                                                      |
|                | 文档引用        | ✅             | ✅           | 都支持                                                                                                   |
|                | 即时应用        | ✅             | ✅           | 都支持                                                                                                   |
| **代码编辑**   | Ctrl+K 快速编辑 | ✅             | ✅           | 都支持                                                                                                   |
|                | 终端命令生成    | ❌             | ✅           | Cursor 独有                                                                                              |
|                | 快速提问        | ✅             | ✅           | 都支持                                                                                                   |
| **智能体**     | Agent 模式      | ✅             | ✅           | 都有智能体功能                                                                                           |
|                | Composer        | ❌             | ✅           | Cursor 自有模型，4x 更快                                                                                 |
|                | Multi-Agent     | 基础           | ⭐⭐⭐⭐⭐   | Cursor 的专用多智能体界面                                                                                |
|                | 并行执行        | ❌             | ✅           | Cursor 可并行多个智能体                                                                                  |
| **代码库理解** | 10 万+ 文件级   | ✅             | ⭐⭐⭐⭐     | Qoder 超大规模优势                                                                                       |
|                | 向量检索        | ✅             | ✅           | 都支持语义检索                                                                                           |
|                | 代码差异可视化  | ❌             | ✅           | Cursor 独有                                                                                              |
| **文档生成**   | Repo Wiki       | ✅             | ❌           | **Qoder 独有**                                                                                           |
|                | Quest Mode      | ✅             | ❌           | **Qoder 独有**                                                                                           |
|                | Spec-Driven     | ✅             | ❌           | **Qoder 独有**                                                                                           |
| **多模态**     | 图片输入        | ❌             | ✅           | Cursor 独有                                                                                              |
|                | 语音输入        | ❌             | ✅           | Cursor 2.0 支持                                                                                          |
| **中文支持**   | 原生中文        | ⭐⭐⭐⭐⭐     | ⭐⭐⭐       | Qoder 针对中文优化                                                                                       |
| **支付方式**   | 支付宝          | ✅             | ❌           | **Qoder 独有**                                                                                           |
|                | 信用卡          | ❌             | ✅           | Cursor 主要方式                                                                                          |
| **价格**       | 月费            | $20-60         | $20-200      | Qoder 更便宜                                                                                             |
|                | 首月优惠        | $2             | ❌           | **Qoder 独有**                                                                                           |
|                | 限时优惠        | **50% off**    | ❌           | **Qoder 暂有：订阅/续费 Pro/Pro+/Ultra 享半价，详见 [优惠详情](https://docs.qoder.com/events/discount)** |
| **社区生态**   | 用户社区        | ⭐⭐⭐         | ⭐⭐⭐⭐⭐   | Cursor 更成熟                                                                                            |
|                | 教程资源        | ⭐⭐⭐         | ⭐⭐⭐⭐⭐   | Cursor 资源更丰富                                                                                        |
|                | 市场成熟度      | 较新（2025.8） | 成熟（2024） | Cursor 更早                                                                                              |

> **重要说明**：
>
> - **✅** 表示支持，**❌** 表示不支持
> - **⭐** 表示功能成熟度/体验评分（1-5 星）
> - Cursor 功能更全面，特别是在代码补全、多模态、智能体协作方面
> - Qoder 在超大规模代码库理解（10 万+ 文件）、自动文档生成（Repo Wiki）、中文支持方面有独特优势

#### Qoder 独有功能

| 功能                        | 说明                                               |
| --------------------------- | -------------------------------------------------- |
| **Repo Wiki**               | ✅ 自动生成项目文档/知识库，持续追踪代码和文档变化 |
| **Quest Mode**              | ✅ 任务导向的自主编程，将需求自动转换为规范并执行  |
| **Spec-Driven Programming** | ✅ 规范驱动编程，开发者只需输入自然语言需求        |
| **10 万+ 文件级检索**       | ✅ 超大规模代码库一次性检索（Cursor 约几万文件级） |
| **原生中文支持**            | ✅ 针对中文场景深度优化                            |
| **支付宝支付**              | ✅ 国内用户支付便捷                                |
| **首月 $2 优惠**            | ✅ 低成本试用                                      |

#### Cursor 独有功能

| 功能                      | 说明                                                    |
| ------------------------- | ------------------------------------------------------- |
| **Composer**              | ✅ Cursor 自有前沿模型，速度提升 4 倍，任务完成 < 30 秒 |
| **Multi-Agent Interface** | ✅ 专用多智能体协作界面，可并行运行多个智能体           |
| **Tab 自动补全**          | ✅ 行业领先的代码补全体验，类似 GitHub Copilot          |
| **光标预测**              | ✅ 预测下一个光标位置，无缝导航代码                     |
| **图片输入**              | ✅ Chat 支持图片作为上下文                              |
| **语音输入**              | ✅ Cursor 2.0 支持语音输入                              |
| **网络搜索**              | ✅ @Web 功能获取最新信息                                |
| **终端命令生成**          | ✅ 在终端使用 Ctrl+K 生成命令                           |
| **代码差异可视化**        | ✅ 更直观的代码变更展示                                 |
| **VS Code 深度集成**      | ✅ 更成熟的生态集成和兼容性                             |
| **活跃社区**              | ✅ 用户基数大，教程资源丰富                             |

#### 功能对比总结

| 功能类型           | Qoder                  | Cursor                            |
| ------------------ | ---------------------- | --------------------------------- |
| **代码补全体验**   | ⭐⭐⭐ 基础补全        | ⭐⭐⭐⭐⭐ 行业领先               |
| **代码库理解规模** | ⭐⭐⭐⭐⭐ 10 万+ 文件 | ⭐⭐⭐⭐ 几万文件级               |
| **多智能体协作**   | ⭐⭐⭐ 基础 Agent      | ⭐⭐⭐⭐⭐ Composer + Multi-Agent |
| **自动文档生成**   | ⭐⭐⭐⭐⭐ Repo Wiki   | ❌ 不支持                         |
| **多模态支持**     | ❌ 不支持              | ⭐⭐⭐⭐⭐ 图片+语音              |
| **中文支持**       | ⭐⭐⭐⭐⭐ 原生优化    | ⭐⭐⭐ 部分支持                   |
| **社区生态**       | ⭐⭐⭐ 较新            | ⭐⭐⭐⭐⭐ 成熟活跃               |
| **功能完整性**     | ⭐⭐⭐ 核心功能        | ⭐⭐⭐⭐⭐ 功能全面               |

**选型建议**：

> **推荐优先级：CLI 为主力，IDE 为补充**

1. **主力工具（强烈推荐）**
   - 所有场景优先 → **GLM-4.7 + Claude Code CLI**
   - 理由：成本效益最高、工程化能力最强、不依赖 IDE

2. **IDE 补充（可选）**
   - 需要超大代码库理解（10 万+ 文件）→ Qoder（中文项目）
   - 追求代码补全体验 → Cursor
   - 需要自动生成项目文档 → Qoder
   - 需要多模态输入（图片/语音）→ Cursor
   - 需要多智能体协作 → Cursor

**核心观点**：

- IDE 适合特定场景（中文、超大代码库、多模态）
- 但 **CLI 才是工程化主力**，更适合复杂任务和团队协作
- 建议团队以 CLI 为主力工具，IDE 仅作补充

### 3.2 CLI 对比：Qoder CLI vs Claude Code CLI

| 对比维度       | Qoder CLI                             | Claude Code CLI (配 GLM-4.7) |
| -------------- | ------------------------------------- | ---------------------------- |
| **代码生成**   | ✅                                    | ✅                           |
| **文件操作**   | ✅ Grep/Read/Write                    | ✅ Read/Write/Edit           |
| **Shell 命令** | ✅ Bash                               | ✅ Bash                      |
| **代码审查**   | ✅ CodeReview                         | ✅                           |
| **子代理机制** | ✅                                    | ✅ Task 工具                 |
| **项目上下文** | ✅                                    | ✅ CLAUDE.md                 |
| **底层模型**   | 多模型智能路由                        | 可配置（GLM-4.7 最优）       |
| **成熟度**     | 较新（2025.10）                       | 成熟（2025.8）               |
| **月费**       | Pro $20 (约 ¥140)、Pro+ $60 (约 ¥420) | **¥40-400**                  |
| **Token 成本** | 2000-6000 点数/月                     | ¥0.6-2.2/百万 tokens         |

**关键差异**：

- **Qoder CLI**：多模型智能路由（Claude/GPT/Gemini/通义千问），Pro 版 $20/月（2000 点数），Pro+ 版 $60/月（6000 点数）
- **Claude Code CLI + GLM-4.7**：月费 **¥40-400**，Token 成本 ¥0.6-2.2/百万 tokens

**选型建议**：推荐 **Claude Code CLI + GLM-4.7** 组合

- Claude Code 提供成熟的工程化框架
- GLM-4.7 提供最新的模型能力（世界排名第 6）
- 成本对比 Qoder 取决于使用量
- Token 成本仅为 Claude 的 12%，GPT 的 30%

### 3.3 主流 AI Coding Plan 价格与使用限制对比

为了让读者更清晰地了解各 AI 编程工具的定价策略和额度限制，以下是主流 Coding Plan 的详细对比：

| AI Coding Plan                    | 月费                           | 刷新周期    | 使用额度（每周期）                       | 额外说明                                     |
| --------------------------------- | ------------------------------ | ----------- | ---------------------------------------- | -------------------------------------------- |
| **GLM-4.7 Lite**                  | ¥40（活动价¥54/季≈¥18/月）     | **每5小时** | 约 **120 次 Prompts**                    | 相当 Claude Pro 用量的 3 倍                  |
| **GLM-4.7 Pro**                   | ¥100（活动价¥270/季≈¥90/月）   | **每5小时** | 约 **600 次 Prompts**                    | 相当 Claude Max 用量的一部分                 |
| **GLM-4.7 Max**                   | ¥400（活动价¥540/季≈¥180/月）  | **每5小时** | 约 **2400 次 Prompts**                   | 相当 Claude Max 5x 用量的 3 倍               |
| **Claude Code Pro**               | $20（≈¥140）                   | **每7天**   | 基础额度                                 | 2025年8月起新增每周限制                      |
| **Claude Code Teams**             | $40/人/月（≈¥280）             | **每7天**   | 团队额度                                 | 2025年8月起新增每周限制                      |
| **Claude Code Max**               | $200（≈¥1400）                 | **每7天**   | 大量额度                                 | 2025年8月起新增每周限制                      |
| **ChatGPT Plus**                  | $20（≈¥140）                   | **每5小时** | 30-150 条消息                            | 还有每周限制（约6-7次完整会话）              |
| **ChatGPT Pro**                   | $200（≈¥1400）                 | **每5小时** | 300-1500条本地消息 或 50-400个云任务     | Codex CLI、Chat、Agent 消耗 premium requests |
| **GitHub Copilot Free**           | $0                             | **每月**    | 2000 次代码补全 + 50 次 premium requests | -                                            |
| **GitHub Copilot Pro**            | $10/月或$100/年（≈¥70-700/年） | **每月**    | 无限标准补全 + Premium requests 限额     | 超出需额外付费                               |
| **Gemini Code Assist Standard**   | $19（≈¥130）                   | **每日**    | 无限代码补全 + 33 次 PR reviews/天       | -                                            |
| **Gemini Code Assist Enterprise** | $45（≈¥310）                   | **每日**    | 无限代码补全 + 100 次 PR reviews/天      | -                                            |
| **Qoder Pro**                     | $20（≈¥140）                   | **每月**    | 2000 点数                                | 超出需额外付费                               |
| **Qoder Pro+**                    | $60（≈¥420）                   | **每月**    | 6000 点数                                | 超出需额外付费                               |
| **Cursor Pro**                    | $20（≈¥140）                   | **每月**    | 基础额度                                 | 使用 Claude/GPT-5.2                          |
| **Cursor Business**               | $40/人/月（≈¥280）             | **每月**    | 团队额度                                 | 使用 Claude/GPT-5.2                          |

> **刷新周期对比**（从快到慢）：
>
> 1. **GLM-4.7 / ChatGPT**：每 **5 小时** 刷新（最快）
> 2. **Gemini Code Assist**：每 **日** 刷新
> 3. **GitHub Copilot / Qoder / Cursor**：每 **月** 刷新
> 4. **Claude Code**：每 **7 天** 刷新（最慢）

> **额度用完后如何继续使用（通用方案）**：
>
> - **方案一**：等待下一个刷新周期自动恢复
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守各服务商条款）
> - **方案四**：升级到更高版本套餐获得更高额度

> **核心结论**：
>
> - **GLM-4.7** 在刷新频率和额度组合上最优（5小时刷新 + 高额度）
> - **ChatGPT Pro** 虽然也是5小时刷新，但价格是 GLM-4.7 Max 的 **3.5 倍**
> - **Claude Code** 的 7 天刷新周期对于重度用户来说限制最大
> - **GitHub Copilot Free** 适合轻度用户，但功能受限
> - **使用 API KEY 是绕过订阅额度限制的最可靠方案**，适合重度用户

---

## 四、GLM-4.7 详细成本分析

### 4.1 价格体系

#### API 按量计费

| 场景                 | 输入 (元/百万 tokens) | 输出 (元/百万 tokens) | 缓存 (元/百万 tokens) |
| -------------------- | --------------------- | --------------------- | --------------------- |
| **短输出 [0, 0.2)**  | ¥0.6                  | ¥2.2                  | ¥0.12                 |
| **中输出 [0.2+)**    | ¥1.5                  | ¥5.5                  | ¥0.30                 |
| **长输入 [32, 200)** | ¥2.2                  | ¥6.6                  | ¥0.44                 |

#### Coding Plan 订阅

| 版本     | 月费                             | 刷新周期    | 使用额度（每周期）     | 折算价格                                       |
| -------- | -------------------------------- | ----------- | ---------------------- | ---------------------------------------------- |
| **Lite** | ¥40/月（活动价¥54/季≈¥18/月）    | **每5小时** | 约 **120 次 Prompts**  | 约为 Claude Code Pro ($20 ≈ ¥140) 的 1/3       |
| **Pro**  | ¥100/月（活动价¥270/季≈¥90/月）  | **每5小时** | 约 **600 次 Prompts**  | 约为 Claude Code Max 的 1/2-2/3                |
| **Max**  | ¥400/月（活动价¥540/季≈¥180/月） | **每5小时** | 约 **2400 次 Prompts** | 约为 Claude Code Max ($200 ≈ ¥1400) 的 1/3-1/4 |
| **对比** | -                                | -           | -                      | Claude Code: $20-200/月 (约 ¥140-1400/月)      |

> **重要说明**：
>
> - **刷新机制**：每 **5 小时** 作为一个周期刷新一次额度
> - 额度重置后自动恢复，无需手动操作
> - 额度用完后需等待下一周期，无法叠加累积
> - 系统不会消耗其他资源包或账户余额
> - Lite 额度约等于 Claude Pro 套餐用量的 **3 倍**
> - Max 额度约等于 Claude Max (5x) 套餐用量的 **3 倍**
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（5小时后自动恢复，一天最多刷新4-5次）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，¥0.6-2.2/百万 tokens，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守服务条款）
> - **方案四**：升级到更高版本套餐获得更高额度

> **成本优势**：
>
> - GLM-4.7 月费仅为 Claude Code 的 **3-29%**
> - GLM-4.7 Token 价格约为 Claude Opus 的 **12%**
> - **5小时刷新周期**比 Claude 的**7天刷新周期**更灵活

### 4.2 用户分级成本估算

#### AI 使用的必然趋势：从轻度到重度

一个重要的观察：**开发者对 AI 的使用量会随时间呈指数级增长**。

```
AI 使用量增长曲线
├── 第一阶段：轻度使用（1-2 个月）
│   ├── 简单代码补全
│   ├── 偶尔咨询问题
│   ├── 10-50 次/天
│   └── 月成本：¥40-100
├── 第二阶段：中度使用（3-6 个月）
│   ├── 日常开发依赖 AI
│   ├── 复杂任务交给 AI
│   ├── 50-200 次/天
│   └── 月成本：¥100-400
└── 第三阶段：重度使用（6 个月+）
    ├── AI 成为核心生产力
    ├── 所有开发任务都通过 AI
    ├── 200-1000+ 次/天
    └── 月成本：¥400-2000+
```

#### 为什么使用量会持续增长？

1. **信任度提升**：从"试试看"到"离不开"
   - 刚开始：怀疑 AI 能力，只敢用简单任务
   - 逐渐：发现 AI 确实能提高效率
   - 最后：将 AI 作为第一生产力工具

2. **能力边界拓展**：从"补全代码"到"自主开发"
   - 刚开始：简单的代码补全、Bug 查询
   - 逐渐：复杂功能开发、架构设计
   - 最后：全需求自主完成、Code Review、重构

3. **依赖性增强**：从"辅助工具"到"核心依赖"
   - 刚开始：偶尔使用，提高 10-20% 效率
   - 逐渐：每天使用，提高 50-100% 效率
   - 最后：无法想象没有 AI 的开发，提高 200-300% 效率

#### 真实数据：使用量增长的必然性

| 时间周期     | 日均使用次数 | 月使用次数 | 月度 Token 估算（GLM-4.7） | 月度成本（GLM-4.7） |
| ------------ | ------------ | ---------- | -------------------------- | ------------------- |
| **第 1 月**  | 20 次        | 600 次     | 30 万 tokens               | ¥40-100             |
| **第 3 月**  | 80 次        | 2400 次    | 120 万 tokens              | ¥100-300            |
| **第 6 月**  | 200 次       | 6000 次    | 300 万 tokens              | ¥300-600            |
| **第 12 月** | 500+ 次      | 15000+ 次  | 750 万+ tokens             | ¥600-1500+          |

> **关键洞察**：
>
> - **使用量 10 倍增长是常态**（从轻度到重度）
> - **成本 10 倍增长不可避免**
> - **如果使用昂贵的模型（如 Claude），月成本可能从 ¥140 飙升到 ¥1400+**
> - **如果使用 GLM-4.7，月成本从 ¥40 增长到 ¥400，压力小得多**

#### 结论：选择高性价比模型的重要性

**因为使用量必然会大幅增长，所以选择高性价比模型至关重要**：

- **Claude Opus**：轻度 ¥140 → 重度 ¥1400+（压力巨大）
- **GLM-4.7**：轻度 ¥40 → 重度 ¥400（可控范围）

> **核心观点**：不要因为当前使用量小就选择昂贵的模型，因为 6 个月后你的使用量会增长 10 倍。**选择一个能让你"用得起、用得爽"的高性价比模型，才能支撑长期的 AI 辅助开发。**

---

根据 [GLM Coding Plan 官方定价](https://bigmodel.cn/glm-coding)：

> **当前活动价（按季付费）**：
>
> - Lite：¥54/季（≈¥18/月）
> - Pro：¥270/季（≈¥90/月）
> - Max：¥540/季（≈¥180/月）
>
> **日常价（按月付费）**：
>
> - Lite：¥40/月
> - Pro：¥100/月
> - Max：¥400/月

| 用户级别 | 月度交互       | GLM-4.7 成本（/人/月）   | Qoder 成本（/人/月） | 节省      |
| -------- | -------------- | ------------------------ | -------------------- | --------- |
| **轻度** | 10-50 次/天    | **¥40**（120次/5小时）   | $20 (约 ¥140)        | **71%**   |
| **中度** | 50-200 次/天   | **¥100**（600次/5小时）  | $20-60 (约 ¥140-420) | **0-76%** |
| **重度** | 200-1000 次/天 | **¥400**（2400次/5小时） | $60 (约 ¥420)        | **5%**    |
| **顶级** | 1000+ 次/天    | **¥400+**（可能多套餐）  | $60+ (约 ¥420+)      | **0-5%**  |

> **结论**：GLM-4.7 在轻度用户场景下节省 71%，中度和重度用户成本接近或略低于 Qoder。

> **刷新机制优势**：
>
> - **GLM-4.7**：每 **5 小时** 刷新一次，一天最多可刷新 **4-5 次**
> - **Lite 版**：每天最多可获得约 **480-600 次** Prompts（120 × 4-5）
> - **Pro 版**：每天最多可获得约 **2400-3000 次** Prompts（600 × 4-5）
> - **Max 版**：每天最多可获得约 **9600-12000 次** Prompts（2400 × 4-5）

> **注意**：
>
> - **GLM-4.7**：按日常价计算，Lite ¥40/月，Pro ¥100/月，Max ¥400/月
> - **Qoder**：Pro $20/月（2000 点数）、Pro+ $60/月（6000 点数），超出点数需额外付费
> - GLM-4.7 世界排名第 6，代码能力更强
> - **5 小时刷新机制**意味着额度恢复更快，适合高频使用场景

### 4.3 真实重度用户案例

#### 案例 1：月预算 $1000（约 ¥7000）用户

**纯 Claude Opus 方案**：

- Claude Code Max 200 订阅费：$200/月（约 ¥1400/月）
- Claude Opus API：$800/月（约 ¥5600/月）
- 可用 tokens：约 2000 万 tokens/月
- **总计：$1000/月（约 ¥7000/月）**

**GLM-4.7 + Claude Code CLI 方案**：

- GLM-4.7 专业版订阅：¥200/月（约 $30/月）
- GLM-4.7 API：¥4800（约 $685）/月
- 可用 tokens：约 **14 亿 tokens/月**
- **总计：¥5000/月（约 $715/月）**
- **效果相同，成本节省 28.5%，tokens 可用量提升 70 倍**

> **成本对比**：
>
> - GLM-4.7 方案：¥5000/月（订阅费 ¥200 + API ¥4800）
> - Claude 方案：¥7000/月（订阅费 ¥1400 + API ¥5600）
> - **节省：¥2000/月（约 28.5%）**

#### 案例 2：月预算 $3000（约 ¥21000）顶级用户

**纯 Claude Opus 方案**：

- Claude Code Max 200 订阅费：$200/月（约 ¥1400/月）
- Claude Opus API：$2800/月（约 ¥19600/月）
- 可用 tokens：约 6000 万 tokens/月
- **总计：$3000/月（约 ¥21000/月）**

**GLM-4.7 + Claude Code CLI 方案**：

- GLM-4.7 专业版订阅：¥400/月（约 $60/月）
- GLM-4.7 API：¥19600（约 $2800）/月
- 可用 tokens：约 **42 亿 tokens/月**
- **总计：¥20000/月（约 $2860/月）**
- **效果相同，成本节省约 5%，tokens 用量提升 70 倍**

> **成本对比**：
>
> - GLM-4.7 方案：¥20000/月（订阅费 ¥400 + API ¥19600）
> - Claude 方案：¥21000/月（订阅费 ¥1400 + API ¥19600）
> - **节省：¥1000/月（约 5%）**
> - 同等预算下，GLM-4.7 可用 tokens 是 Claude 的 **7 倍**

---

## 五、为什么选择 CLI 而不是编辑器插件？

> **核心观点**：CLI（命令行界面）是 AI 辅助编程的未来方向，比编辑器插件更先进、更强大、更灵活。

### 5.1 CLI vs 编辑器插件对比

#### 为什么 CLI 更先进？

```
CLI vs 编辑器插件对比
├── CLI 优势
│   ├── 更强大的 Agent 架构
│   │   ├── 子代理机制（Task 工具）
│   │   ├── 并行处理能力
│   │   └── 复杂任务拆解
│   ├── 更完整的工具链
│   │   ├── Read/Write/Edit 文件操作
│   │   ├── Bash 命令执行
│   │   ├── Grep 搜索
│   │   ├── LSP 集成
│   │   └── Git 操作
│   ├── 项目级上下文
│   │   ├── CLAUDE.md 配置
│   │   ├── 全局代码理解
│   │   └── 跨文件协作
│   ├── 更高的灵活性
│   │   ├── 可配置使用任意模型
│   │   ├── 自定义工具和脚本
│   │   └── 不依赖特定 IDE
│   ├── 完整的插件生态系统 ⭐
│   │   ├── PR Review Toolkit（代码审查）
│   │   ├── Development Workflows（专业工作流）
│   │   ├── Document Skills（文档处理）
│   │   ├── Code Quality Tools（代码质量）
│   │   ├── Enterprise Plugins（150+命令）
│   │   └── 详见：claude-plugins.dev
│   └── 更好的可移植性
│       ├── 跨平台使用
│       ├── 远程服务器开发
│       └── CI/CD 集成
└── 编辑器插件局限
    ├── 受限于 IDE 界面
    ├── 工具链不完整
    ├── 缺乏复杂 Agent 能力
    ├── 没有插件生态
    └── 难以跨工具使用
```

**核心观点**：

- **CLI 是工程化工具，编辑器插件是辅助工具**
- **CLI 可以处理复杂的、多步骤的任务**
- **CLI 不依赖特定 IDE，更灵活**
- **CLI 拥有完整的插件生态系统，可对接各种工程化规范** ⭐
- **CLI 代表 AI 辅助编程的未来方向**

### 5.2 Claude Code CLI 插件生态系统

Claude Code CLI 拥有一个强大的插件市场，支持对接各种 AI 工程化规范：

| 插件类型                  | 功能描述                                                       | 安装命令                                                                           |
| ------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **PR Review Toolkit**     | 自动化代码审查（测试、错误处理、类型设计、代码质量、代码简化） | `npx claude-plugins install @anthropics/claude-code-plugins/pr-review-toolkit`     |
| **Python Development**    | Python 3.12+、Django、FastAPI、async patterns                  | `npx claude-plugins install @wshobson/claude-code-workflows/python-development`    |
| **JavaScript/TypeScript** | ES6+、Node.js、React、现代 Web 框架                            | `npx claude-plugins install @wshobson/claude-code-workflows/javascript-typescript` |
| **Backend Development**   | API 设计、GraphQL 架构、TDD 后端开发                           | `npx claude-plugins install @wshobson/claude-code-workflows/backend-development`   |
| **Frontend Excellence**   | React 19、Next.js 15、组件架构、状态管理                       | `npx claude-plugins install @dotclaude/dotclaude-plugins/frontend-excellence`      |
| **Document Skills**       | Excel、Word、PowerPoint、PDF 文档处理                          | `npx claude-plugins install @anthropics/anthropic-agent-skills/document-skills`    |
| **Code Refactoring**      | 代码清理、重构自动化、技术债务管理                             | `npx claude-plugins install @wshobson/claude-code-workflows/code-refactoring`      |
| **Claude Flow**           | 150+ 命令、74+ 专业代理、GitHub 集成                           | `npx claude-plugins install @ruvnet/claude-flow-marketplace/claude-flow`           |
| **Developer Essentials**  | Git、SQL、错误处理、代码审查、E2E 测试                         | `npx claude-plugins install @wshobson/claude-code-workflows/developer-essentials`  |

> **关键优势**：
>
> - **150+ 专业命令**：覆盖开发全流程
> - **74+ 专业代理**：针对不同技术栈和工作流
> - **一键安装**：`npx claude-plugins install <plugin-name>`
> - **开源社区**：持续更新，社区维护
> - **详见**：[Claude Plugins Marketplace](https://claude-plugins.dev/)

### 5.3 Claude Code：AI 工程化规范的制定者

**重要观点**：Claude Code 不仅仅是一个工具，更是 **AI 工程化规范的制定者之一**。

#### Anthropic 的 AI 规范制定角色

**Anthropic（Claude 的开发商）是全球 AI 安全和工程化规范的核心制定者**：

1. **Responsible Scaling Policy (RSP)**
   - Anthropic 制定了前沿 AI 模型的安全和部署标准
   - 定义了技术安全和运营措施的最佳实践
   - 详见：[Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)

2. **AI Safety Levels (ASL) 标准**
   - 参照美国政府生物安全级别（BSL）框架
   - 建立了分级的 AI 安全标准体系
   - 2025 年 5 月激活了 ASL-3 保护措施
   - 详见：[ASL-3 Protections](https://www.anthropic.com/news/activating-asl3-protections)

3. **Claude Code 官方最佳实践**
   - Anthropic 发布了官方的 AI 编码最佳实践
   - 定义了企业级 AI 编码的标准和流程
   - 涵盖治理、安全、CI/CD 集成、代码审查等
   - 详见：[Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)

4. **合规框架**
   - 为加州 SB-53 等 AI 法规制定合规框架
   - 参与全球 AI 安全标准的制定
   - 详见：[Compliance Framework SB-53](https://www.anthropic.com/news/compliance-framework-SB53)

#### 为什么这很重要？

| 维度             | 其他 AI 工具   | Claude Code CLI             |
| ---------------- | -------------- | --------------------------- |
| **规范来源**     | 遵循第三方规范 | **规范制定者本身**          |
| **工程化标准**   | 自定义或不完整 | **符合企业级标准**          |
| **安全最佳实践** | 社区实践       | **官方制定的安全标准**      |
| **企业采用**     | 需要额外评估   | **直接采用行业标准**        |
| **长期支持**     | 取决于商业公司 | **AI 规范制定者的核心产品** |

> **核心结论**：
>
> - Claude Code 由 **AI 规范制定者**（Anthropic）开发和维护
> - 采用 Claude Code = 采用 **AI 工程化的行业标准**
> - 这不是选择一个工具，而是选择一个 **经过验证的工程化体系**
> - 对于企业来说，这意味着更低的风险、更高的合规性、更成熟的最佳实践

> **企业优势**：
>
> - Anthropic 与全球政府、企业合作制定 AI 标准
> - Claude Code 内置了这些标准和最佳实践
> - 使用 Claude Code = 自动符合行业领先的 AI 工程化规范

---

## 六、实施建议

### 6.1 推荐方案总览

```
┌─────────────────────────────────────────────────────────┐
│                    AI 编程工具选型方案                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  核心模型：GLM-4.7（智谱最新旗舰，2025.12 发布）         │
│  ├── 价格：Claude 的 1/7 - 1/12                         │
│  ├── 能力：代码能力超越 GPT-5（宣称）                   │
│  ├── 世界排名第 6                                       │
│  └── 原则：用新不用旧                                    │
│                                                         │
│  工程化框架：Claude Code CLI + GLM-4.7                  │
│  ├── 成熟 Agent 架构                                    │
│  ├── 低成本订阅（GLM-4.7 月费 ¥40-400）                 │
│  ├── 可配置使用 GLM-4.7                                 │
│  ├── 项目级上下文管理                                    │
│  ├── CLI 比编辑器插件更强大、更灵活                      │
│  ├── 插件生态：150+ 命令、74+ 代理                       │
│  └── AI 规范制定者：Anthropic 核心产品                   │
│                                                         │
│  工具理念：CLI 为主力，IDE 为前沿探索                    │
│  ├── CLI：工程化工具，适合复杂任务                      │
│  ├── 插件系统：对接各种工程化规范                        │
│  ├── 行业标准：符合企业级 AI 安全规范                    │
│  ├── IDE：了解前沿技术，不建议作为主力                   │
│  └── 灵活选择，以成本效率为先                            │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 6.2 分阶段实施计划

#### 第一阶段：试点验证（1-2 周）

| 步骤 | 内容                          | 目标           | 成本                      |
| ---- | ----------------------------- | -------------- | ------------------------- |
| 1    | 注册智谱 AI，申请 GLM-4.7 API | 获得访问权限   | ¥0（赠送 2000 万 tokens） |
| 2    | 安装 Claude Code CLI          | 验证工程化能力 | **¥0（免费安装）**        |
| 3    | 订阅 GLM-4.7 基础版并配置     | 验证模型配置   | ¥40（测试订阅费）         |
| 4    | 小范围试点（2-3 人）          | 收集反馈       | ¥120-200                  |

**阶段目标**：验证 GLM-4.7 + Claude Code CLI 组合的可行性

**成本优势**：月费仅 **¥40**，远低于 Claude Code Pro（$20 ≈ ¥140）

#### 第二阶段：团队推广（1-2 个月）

| 步骤 | 内容                       | 覆盖范围   | 成本        |
| ---- | -------------------------- | ---------- | ----------- |
| 1    | 内部分享会（CLI 使用技巧） | 全体开发者 | ¥0          |
| 2    | 推广 Claude Code CLI       | 10-20 人   | ¥0（免费）  |
| 3    | GLM-4.7 订阅配额           | 按需分配   | ¥400-800/月 |
| 4    | 建立 CLI 使用最佳实践      | 团队文档化 | ¥0          |

**阶段目标**：50%+ 开发者采用 CLI 方案

**成本优势**：GLM-4.7 订阅费仅为 Claude Code Teams 的 **3-29%**

#### 第三阶段：全面应用（持续）

| 步骤 | 内容                 | 目标           |
| ---- | -------------------- | -------------- |
| 1    | 评估私有化部署       | 20+ 人团队考虑 |
| 2    | 建立 AI 工程最佳实践 | 团队内部文档化 |
| 3    | 持续优化成本         | 多工具混合策略 |

### 6.3 不同场景的推荐配置

#### 个人开发者

| 预算                    | 配置方案                  | 月度成本                |
| ----------------------- | ------------------------- | ----------------------- |
| ¥200 以内（约 $30）     | GLM-4.7 基础版 + API 按需 | ¥60-150（约 $10-22）    |
| ¥500-1000（约 $70-140） | GLM-4.7 基础版 + 大量 API | ¥200-500（约 $30-72）   |
| ¥2000+（约 $280+）      | GLM-4.7 专业版 + 海量 API | ¥500-1500（约 $72-215） |

**注意**：以上价格包含 GLM-4.7 订阅费（¥40-400）+ API 费用

#### 小团队（2-5 人）

| 预算             | 配置方案                      | 月度成本         | 人均                      |
| ---------------- | ----------------------------- | ---------------- | ------------------------- |
| ¥2000（约 $280） | GLM-4.7 基础版团队 + API      | ¥2000（约 $280） | ¥400-1000（约 $55-140）   |
| ¥5000（约 $700） | GLM-4.7 专业版团队 + 大量 API | ¥5000（约 $700） | ¥1000-2500（约 $140-350） |

**注意**：GLM-4.7 月费远低于 Claude Teams（$40/人/月 ≈ ¥280/人/月）

#### 中型团队（5-20 人）

| 预算                          | 配置方案                      | 月度成本                      | 人均                    |
| ----------------------------- | ----------------------------- | ----------------------------- | ----------------------- |
| ¥10000-20000（约 $1400-2800） | GLM-4.7 专业版团队 + 大量 API | ¥10000-20000（约 $1400-2800） | ¥500-4000（约 $70-560） |

**注意**：相比 Claude Code Teams（$40/人/月 ≈ ¥280/人/月），**节省 ¥5600-11200/月（$800-1600/月）订阅费**

#### 大型团队（20+ 人）

| 预算                       | 配置方案           | 月度成本             | 说明       |
| -------------------------- | ------------------ | -------------------- | ---------- |
| ¥50000+/月（约 $7000+/月） | GLM-4.7 私有化部署 | ¥50000+（约 $7000+） | 考虑私有化 |

**注意**：如果使用 GLM-4.7，相比 Claude Code Teams 节省约 **$800/月（¥5600/月）**

---

## 七、成本效益分析

### 7.1 投资回报率（ROI）

假设团队有 10 名开发者，平均年薪 ¥30 万：

| 方案                      | 月度成本     | 年度成本       | 效率提升 | 年度价值 | ROI            |
| ------------------------- | ------------ | -------------- | -------- | -------- | -------------- |
| **GLM-4.7 + Claude Code** | ¥10400-14400 | ¥124800-172800 | 30%      | ¥9000000 | **5200-7200%** |
| **Claude Code 原生**      | ¥14280-15400 | ¥171360-184800 | 30%      | ¥9000000 | 4870-5250%     |
| **无 AI**                 | ¥0           | ¥0             | 0%       | ¥0       | 0%             |

> **结论**：GLM-4.7 方案的 ROI 与 Claude Code 相当，但成本降低 **27-43%**。

### 7.2 真实成本对比

#### 10 人团队，月预算 ¥10000（约 $1400）

**Claude Code 原生方案**：

- Claude Code Teams：$40 × 10 = $400 ≈ ¥2800（**必需订阅费**）
- Claude Opus API：$857 ≈ ¥6000
- 可用 tokens：约 350 万/月
- **总计：$1257/月（约 ¥8800/月）**

**GLM-4.7 + Claude Code CLI 方案**：

- Claude Code CLI：¥0（免费）
- GLM-4.7 专业版订阅：¥400
- GLM-4.7 API：¥9600
- 可用 tokens：约 **48 亿/月**
- **总计：¥10000/月（约 $1400/月）**

> **关键洞察**：相同预算 ¥10000（约 $1400）下：
>
> - GLM-4.7 可用 tokens 是 Claude Opus 的 **1370+ 倍**
> - GLM-4.7 月费仅为 Claude Teams 的 **14%**
> - 总成本节省约 **¥1240/月（约 $177/月）**

#### 20 人团队对比

| 方案             | 订阅费（月） | API 成本（月） | 总成本（年）     |
| ---------------- | ------------ | -------------- | ---------------- |
| **Claude Teams** | $800 (¥5600) | ¥10000         | ¥187,200         |
| **GLM-4.7 方案** | ¥400-800     | ¥14400-19600   | ¥178,800-244,800 |

**同样年度预算下**：

- Claude Teams：$800 × 12 = $9600/年 订阅费（约 ¥67,200）
- GLM-4.7 方案：¥4800-9600/年 订阅费，仅为 Claude 的 **7-14%**
- 将更多预算用于 API，获得 **14-140 倍以上**的 tokens

---

## 八、风险与挑战

### 8.1 潜在风险

| 风险               | 影响               | 缓解措施               |
| ------------------ | ------------------ | ---------------------- |
| **GLM-4.7 稳定性** | 新模型可能有 bug   | 试点验证，逐步推广     |
| **学习曲线**       | 团队需要适应新工具 | 内部分享，文档沉淀     |
| **供应商锁定**     | 过度依赖单一供应商 | 保持多工具能力         |
| **成本控制**       | API 使用可能超预期 | 设置预算告警，定期审查 |

### 8.2 应对策略

1. **双模型策略**：保留 Claude 作为备选
2. **分阶段推广**：从小范围试点开始
3. **成本监控**：每月审查 API 使用情况
4. **持续评估**：关注新模型发布

---

## 九、总结与建议

### 9.1 核心建议

> **推荐采用 GLM-4.7 + Claude Code CLI 组合方案**

这是基于成本效益、工程化能力、插件生态系统和行业标准综合评估后的最优选择。

---

### 9.2 关键论点

1. **用新不用旧**：GLM-4.7 是 2025 年 12 月最新旗舰，技术领先
2. **成本优势明显**：月费仅为 Claude 的 3-29%，Token 成本为 12%
3. **工程化能力成熟**：Claude Code CLI 提供完整框架
4. **可配置性强**：Claude Code CLI 可直接使用 GLM-4.7
5. **CLI 更先进**：CLI 比编辑器插件更强大、更灵活、更工程化
6. **插件生态系统完善**：150+ 专业命令、74+ 专业代理，覆盖各种工程化规范
7. **AI 规范制定者**：Anthropic 是全球 AI 安全和工程化规范的核心制定者
8. **不依赖 IDE**：CLI 可在任何环境使用，包括远程服务器

---

### 9.3 预期收益

| 收益类型       | 预期值     | 说明                      |
| -------------- | ---------- | ------------------------- |
| **月费节省**   | 71-97%     | GLM-4.7 订阅费仅 ¥40-400  |
| **总成本节省** | 27-43%     | 含订阅费和 Token 成本     |
| **Token 提升** | 14-1400x   | 相同预算下可用 Token 数量 |
| **能力提升**   | 20-50%     | 开发效率提升              |
| **ROI**        | 5200-7200% | 投资回报率                |

> **核心优势总结**：
>
> - **GLM-4.7**：世界排名第 6，月费 ¥40-400，Token 价格为 Claude 的 12%
> - **Claude Code CLI**：免费工具，比编辑器插件更强大、更灵活
> - **插件生态**：150+ 命令、74+ 代理，覆盖各种工程化规范
> - **AI 规范制定者**：Anthropic 是全球 AI 安全和工程化规范的核心制定者
> - **组合效果**：**行业标准 + CLI 工程化能力 + 插件生态 + 高性价比模型**

---

### 9.4 企业级优势：选择 AI 规范制定者的工具

#### 为什么企业应该选择 Claude Code CLI？

对于企业来说，选择 AI 工具不仅是选择一个产品，更是选择一套**工程化体系和标准**。

| 对比维度       | 其他 AI 工具（Qoder/Cursor 等） | Claude Code CLI + GLM-4.7       |
| -------------- | ------------------------------- | ------------------------------- |
| **规范来源**   | 遵循第三方规范或自定义规范      | **规范制定者本身**（Anthropic） |
| **安全标准**   | 社区实践或商业公司标准          | **官方 AI 安全标准（ASL-3）**   |
| **工程化规范** | 不完整或自定义                  | **企业级最佳实践**              |
| **合规性**     | 需要额外评估和适配              | **符合全球 AI 法规框架**        |
| **长期维护**   | 取决于商业公司生存              | **AI 规范制定者的核心产品**     |
| **风险控制**   | 较高（工具风险 + 合规风险）     | **低（行业标准 + 合规保障）**   |

#### 企业级场景的实际价值

**1. 金融、医疗等高度监管行业**

- 需要符合严格的安全和合规要求
- Claude Code 基于 Anthropic 的 Responsible Scaling Policy
- 自动符合全球领先的 AI 安全标准
- **降低合规风险，提高审计通过率**

**2. 大型企业 IT 部门**

- 需要标准化的工程流程
- Claude Code 提供官方最佳实践
- 与 CI/CD、代码审查、安全审计无缝集成
- **统一标准，降低管理成本**

**3. 政府机构和公共部门**

- 需要透明、可审计的 AI 使用
- Anthropic 与政府合作制定 AI 标准
- 符合加州 SB-53 等法规框架
- **满足政策要求，提高公众信任**

**4. 国际化企业**

- 需要符合全球不同地区的 AI 法规
- Anthropic 参与全球 AI 安全标准制定
- 一套方案，全球适用
- **简化合规流程，降低法律风险**

#### 结论

> **核心观点**：选择 Claude Code CLI = 选择 **AI 工程化的行业标准**
>
> - 这不是一个工具选择，而是一个**战略选择**
> - 降低企业风险、提高合规性、获得长期保障
> - 对于企业级部署，这是**最优解**

---

### 9.5 工具选择的灵活性

> **重要原则：允许开发者选择最适合自己的 AI 工具**

虽然我们推荐 **GLM-4.7 + Claude Code CLI** 作为主力方案，但**强烈鼓励开发者接触和体验世界最先进的 AI 工具组合**：

#### 为什么要允许开发者自由选择？

1. **接触前沿技术**
   - **Cursor + Claude Opus + GPT-5.2/Codex** 是目前世界上最先进的组合
   - 通过使用最顶级的 AI 工程化能力，了解 AI 辅助编程的最新进展
   - 体验最新的 AI 特性和交互模式

2. **反哺团队**
   - 将前沿工具的使用经验和最佳实践带回团队
   - 帮助团队判断哪些新特性值得在主力方案中采用
   - 提供多维度的技术选型视角

3. **个人成长**
   - 保持技术敏感度，走在 AI 前沿
   - 培养对 AI 工具的判断力
   - 避免"工具孤岛"思维

#### 推荐的前沿工具组合

| 工具组合                           | 特点                           | 适用场景         | 预算             |
| ---------------------------------- | ------------------------------ | ---------------- | ---------------- |
| **Cursor + Claude Opus + GPT-5.2** | 世界最强组合，Composer 4x 速度 | 追求极致效率     | $200/月 (≈¥1400) |
| **Cursor + GPT-5.2-Codex-Max**     | OpenAI 最新代码模型            | 体验 OpenAI 生态 | $100-200/月      |
| **Claude Code + Claude Opus 4.5**  | Anthropic 原生组合             | 深度体验 Claude  | $20-200/月       |

> **核心观点**：
>
> - **主力方案**（GLM-4.7 + Claude Code CLI）：追求**性价比和稳定性**
> - **前沿探索**（Cursor + Claude + Codex）：追求**技术领先和经验积累**
> - **两者并不冲突**，而是**相辅相成**

#### 实施建议

1. **团队标准方案**：采用 **GLM-4.7 + Claude Code CLI** 作为主力工具
   - 优先使用 CLI 进行日常开发
   - 享受 CLI 的工程化能力和灵活性
   - 降低团队成本，提高效率

2. **个人前沿探索**：鼓励开发者体验 Cursor、Qoder 等 IDE
   - 了解 AI 工具的最新进展
   - 但不建议作为主力工具（成本高、依赖 IDE）
   - 将 IDE 的优秀特性反馈到 CLI 使用中

3. **知识分享**：定期内部分享会
   - 分享 CLI 使用技巧和最佳实践
   - 交流前沿 IDE 工具的体验
   - 建立团队的 AI 工具使用规范

4. **技术雷达**：建立 AI 工具评估机制
   - 持续关注新模型发布
   - 评估 CLI 工具的新特性
   - 保持技术敏感度

> **最终目标**：以 **CLI 为主力工具**，以 **IDE 为前沿探索**，既保证成本效率，又保持技术敏感度。

---

## 十、代码生成能力深度分析

### 10.1 AI 代码生成现状评估

#### 整体能力评估

| 能力维度     | 前端           | 后端           | 评分     |
| ------------ | -------------- | -------------- | -------- |
| **代码生成** | UI 还原度高    | 逻辑正确率高   | ⭐⭐⭐⭐ |
| **架构设计** | 组件化良好     | 分层合理       | ⭐⭐⭐   |
| **Bug 率**   | 样式问题多     | 边界情况多     | ⭐⭐⭐   |
| **调试难度** | 视觉问题难定位 | 逻辑问题易定位 | ⭐⭐⭐   |

#### 前端代码生成

**优势**：

- ✅ UI 组件还原度高（80-90%）
- ✅ 响应式布局理解到位
- ✅ 组件化思想成熟
- ✅ TailwindCSS 等工具库使用准确

**常见问题**：

- ❌ 样式细节不够精细（间距、颜色、圆角等）
- ❌ 交互逻辑偶尔有 bug（事件处理、状态管理）
- ❌ 复杂动画效果实现不理想
- ❌ 浏览器兼容性考虑不足
- ❌ 性能优化意识较弱（重复渲染、不必要的计算）

**调试难度**：⭐⭐⭐⭐（视觉问题需要逐像素对比）

#### 后端代码生成

**优势**：

- ✅ CRUD 生成准确（90-95%）
- ✅ API 设计规范（RESTful）
- ✅ 数据库操作正确（SQL/ORM）
- ✅ 错误处理机制完善
- ✅ 代码结构清晰

**常见问题**：

- ❌ 复杂业务逻辑理解偏差
- ❌ 并发/安全问题（锁、事务）
- ❌ 性能优化不足（N+1 查询、缓存）
- ❌ 边界情况处理不完整
- ❌ 安全漏洞（SQL 注入、XSS）
- ❌ 日志和监控不足

**调试难度**：⭐⭐⭐（逻辑问题可通过日志快速定位）

### 10.2 跨域开发可能性分析

#### 前端开发者写后端

| 能力要求       | 现状         | 可行性   |
| -------------- | ------------ | -------- |
| **API 设计**   | 理解概念     | ⭐⭐⭐⭐ |
| **数据库操作** | 需要学习 SQL | ⭐⭐⭐   |
| **业务逻辑**   | 转换思维模式 | ⭐⭐⭐   |
| **部署运维**   | 完全新领域   | ⭐⭐     |

**可行性评估**：

- 简单 CRUD：**85% 可行**（AI 辅助下）
- 中等复杂度：**60% 可行**
- 高复杂度：**30% 可行**

**学习曲线**：

- 基础后端概念（API、数据库）：**1-2 周**
- 实战项目（简单 CRUD）：**1 个月**
- 生产级应用：**3-6 个月**

#### 后端开发者写前端

| 能力要求              | 现状         | 可行性   |
| --------------------- | ------------ | -------- |
| **HTML/CSS**          | 基础了解     | ⭐⭐⭐⭐ |
| **JavaScript/TS**     | 需要深入     | ⭐⭐⭐   |
| **框架（React/Vue）** | 需要系统学习 | ⭐⭐⭐   |
| **UI/UX 设计**        | 完全新领域   | ⭐⭐     |

**可行性评估**：

- 简单页面：**80% 可行**（AI 辅助下）
- 中等复杂度：**50% 可行**
- 高复杂度（动画、交互）：**25% 可行**

**学习曲线**：

- 基础 HTML/CSS/JS：**2-3 周**
- 单页面应用框架：**1-2 个月**
- 生产级应用（状态管理、性能优化）：**3-6 个月**

### 10.3 完成需求的成本预估

#### 个人开发者完成一个需求

| 需求类型       | 传统开发 | AI 辅助开发 | 效率提升   |
| -------------- | -------- | ----------- | ---------- |
| **简单页面**   | 4-8 小时 | 1-2 小时    | **4-6x**   |
| **CRUD 功能**  | 1-2 天   | 2-4 小时    | **3-4x**   |
| **中等复杂度** | 3-5 天   | 1-2 天      | **2-3x**   |
| **高复杂度**   | 1-2 周   | 3-7 天      | **1.5-2x** |

#### 团队开发成本对比

假设 10 人团队，月薪 ¥30,000：

| 开发模式     | 月度人力成本 | AI 工具成本 | 总成本   | 产出对比 |
| ------------ | ------------ | ----------- | -------- | -------- |
| **传统开发** | ¥300,000     | ¥0          | ¥300,000 | 1x       |
| **AI 辅助**  | ¥300,000     | ¥10,000     | ¥310,000 | **2-3x** |

> **结论**：AI 辅助下，**10% 的成本增加带来 200-300% 的产出提升**。

### 10.4 AI 生成代码的常见问题

#### 前端问题分布

| 问题类型     | 占比 | 调试难度   | 预防措施            |
| ------------ | ---- | ---------- | ------------------- |
| **样式细节** | 40%  | ⭐⭐⭐     | 精确描述设计稿      |
| **交互逻辑** | 25%  | ⭐⭐⭐⭐   | 明确状态流转        |
| **性能问题** | 20%  | ⭐⭐⭐⭐⭐ | 代码审查 + 性能测试 |
| **兼容性**   | 10%  | ⭐⭐⭐⭐   | 指定浏览器支持      |
| **其他**     | 5%   | ⭐⭐       | -                   |

#### 后端问题分布

| 问题类型         | 占比 | 调试难度   | 预防措施        |
| ---------------- | ---- | ---------- | --------------- |
| **业务逻辑偏差** | 35%  | ⭐⭐⭐     | 详细需求文档    |
| **边界情况**     | 25%  | ⭐⭐⭐⭐   | 完整测试用例    |
| **性能问题**     | 20%  | ⭐⭐⭐⭐⭐ | 性能测试 + 优化 |
| **安全问题**     | 15%  | ⭐⭐⭐⭐⭐ | 安全审查        |
| **其他**         | 5%   | ⭐⭐       | -               |

### 10.5 调试 AI 生成代码所需能力

#### 前端调试能力图谱

```
前端调试能力
├── 基础能力
│   ├── 浏览器 DevTools 使用
│   ├── Console 日志调试
│   ├── 断点调试
│   └── 网络请求分析
├── 样式调试
│   ├── CSS 选择器优先级
│   ├── Flexbox/Grid 布局
│   ├── 响应式断点
│   └── 浏览器兼容性
├── 交互调试
│   ├── 事件处理机制
│   ├── 状态管理（Redux/Vuex/Pinia）
│   ├── 异步操作（Promise/async-await）
│   └── 生命周期钩子
└── 性能调试
    ├── React DevTools / Vue DevTools
    ├── 性能分析（Performance）
    ├── 内存泄漏检测
    └── 渲染优化
```

#### 后端调试能力图谱

```
后端调试能力
├── 基础能力
│   ├── 日志系统使用
│   ├── 断点调试
│   ├── 单元测试
│   └── 集成测试
├── 逻辑调试
│   ├── 业务流程追踪
│   ├── 数据流转分析
│   ├── 错误堆栈分析
│   └── 边界情况测试
├── 性能调试
│   ├── 慢查询分析
│   ├── 接口性能测试
│   ├── 内存/CPU 分析
│   └── 缓存命中率
└── 安全调试
    ├── SQL 注入检测
    ├── XSS/CSRF 防护
    ├── 权限验证
    └── 数据加密
```

### 10.6 前后端互相调试的缺失能力

#### 前端开发调试后端缺失能力

| 缺失能力         | 重要程度   | 学习周期 | 影响范围 |
| ---------------- | ---------- | -------- | -------- |
| **API 设计规范** | ⭐⭐⭐⭐⭐ | 1 周     | 接口对接 |
| **数据库基础**   | ⭐⭐⭐⭐⭐ | 2 周     | 数据理解 |
| **服务器部署**   | ⭐⭐⭐     | 1 个月   | 环境搭建 |
| **日志分析**     | ⭐⭐⭐⭐   | 2 周     | 问题定位 |
| **性能优化**     | ⭐⭐⭐     | 1 个月   | 系统优化 |
| **安全意识**     | ⭐⭐⭐⭐   | 持续     | 系统安全 |

**学习优先级**：

1. API 设计 + 数据库基础（**必须**，2-3 周）
2. 日志分析（**重要**，2 周）
3. 服务器部署（**建议**，1 个月）
4. 性能优化 + 安全（**持续**）

#### 后端开发调试前端缺失能力

| 缺失能力              | 重要程度   | 学习周期 | 影响范围 |
| --------------------- | ---------- | -------- | -------- |
| **CSS/Flexbox**       | ⭐⭐⭐⭐⭐ | 2 周     | 页面布局 |
| **JavaScript 深入**   | ⭐⭐⭐⭐⭐ | 1 个月   | 交互逻辑 |
| **框架（React/Vue）** | ⭐⭐⭐⭐⭐ | 1-2 个月 | 组件开发 |
| **浏览器 DevTools**   | ⭐⭐⭐⭐   | 1 周     | 问题定位 |
| **UI/UX 基础**        | ⭐⭐⭐     | 持续     | 用户体验 |
| **前端性能优化**      | ⭐⭐⭐     | 1 个月   | 体验优化 |

**学习优先级**：

1. CSS/Flexbox + 浏览器 DevTools（**必须**，2-3 周）
2. JavaScript 深入 + 框架（**必须**，2-3 个月）
3. UI/UX + 性能优化（**建议**，持续）

### 10.7 AI 辅助下的学习路径

#### 路径一：前端开发者 → 全栈（AI 辅助）

**学习周期**：3-6 个月

| 阶段         | 时间    | 内容                                          | AI 辅助效果 |
| ------------ | ------- | --------------------------------------------- | ----------- |
| **第一阶段** | 2-4 周  | 后端基础（Node.js/Express、API 设计、数据库） | ⭐⭐⭐⭐⭐  |
| **第二阶段** | 4-8 周  | 实战项目（CRUD、认证、文件上传）              | ⭐⭐⭐⭐    |
| **第三阶段** | 4-12 周 | 生产级应用（部署、监控、性能优化）            | ⭐⭐⭐      |

**预期效果**：

- 3 个月后：能独立完成 80% 的全栈需求
- 6 个月后：能独立完成 95% 的全栈需求

#### 路径二：后端开发者 → 全栈（AI 辅助）

**学习周期**：4-8 个月

| 阶段         | 时间    | 内容                             | AI 辅助效果 |
| ------------ | ------- | -------------------------------- | ----------- |
| **第一阶段** | 3-4 周  | 前端基础（HTML/CSS、JavaScript） | ⭐⭐⭐⭐    |
| **第二阶段** | 8-12 周 | 框架深入（React/Vue、状态管理）  | ⭐⭐⭐      |
| **第三阶段** | 8-16 周 | 生产级应用（性能优化、部署）     | ⭐⭐⭐      |

**预期效果**：

- 4 个月后：能独立完成 70% 的前端需求
- 8 个月后：能独立完成 90% 的前端需求

#### 路径三：零基础 → AI 辅助开发（GLM-4.7）

**学习周期**：6-12 个月

| 阶段         | 时间    | 内容                             | AI 辅助效果 |
| ------------ | ------- | -------------------------------- | ----------- |
| **第一阶段** | 4-8 周  | 编程基础（语法、数据结构、算法） | ⭐⭐⭐      |
| **第二阶段** | 8-12 周 | 前端或后端专项                   | ⭐⭐⭐⭐    |
| **第三阶段** | 8-16 周 | 框架 + 工程化                    | ⭐⭐⭐⭐    |
| **第四阶段** | 8-24 周 | 实战项目 + 调试能力              | ⭐⭐⭐      |

**预期效果**：

- 6 个月后：能独立完成简单需求
- 12 个月后：能独立完成中等复杂度需求

### 10.8 掌握 AI 辅助开发的关键能力

#### 核心能力清单

| 能力                   | 重要程度   | 学习周期  | AI 辅助效果 |
| ---------------------- | ---------- | --------- | ----------- |
| **Prompt Engineering** | ⭐⭐⭐⭐⭐ | 1-2 周    | -           |
| **需求理解与拆解**     | ⭐⭐⭐⭐⭐ | 持续      | ⭐⭐⭐      |
| **代码阅读能力**       | ⭐⭐⭐⭐⭐ | 2-3 个月  | ⭐⭐        |
| **调试能力**           | ⭐⭐⭐⭐⭐ | 3-6 个月  | ⭐⭐⭐      |
| **架构设计**           | ⭐⭐⭐⭐   | 6-12 个月 | ⭐⭐⭐⭐    |
| **测试能力**           | ⭐⭐⭐⭐   | 1-2 个月  | ⭐⭐⭐⭐    |

#### 学习建议

1. **先掌握 Prompt Engineering**（1-2 周）
   - 学习如何清晰描述需求
   - 学习如何分步骤拆解任务
   - 学习如何提供上下文

2. **提升代码阅读能力**（2-3 个月）
   - 阅读开源项目代码
   - 理解常见设计模式
   - 熟悉框架最佳实践

3. **重点培养调试能力**（3-6 个月）
   - 前端：精通浏览器 DevTools
   - 后端：掌握日志系统和测试
   - 通用的：问题定位思路

4. **架构设计能力**（6-12 个月）
   - 学习系统设计
   - 理解设计模式
   - 关注性能和安全

### 10.9 成功掌握 AI 辅助开发的估算

#### 不同基础的学习周期

| 当前基础                 | 达成目标            | 学习周期  | 每周投入   | 成功概率 |
| ------------------------ | ------------------- | --------- | ---------- | -------- |
| **有编程基础（1-2 年）** | AI 辅助完成中等需求 | 1-2 个月  | 10-15 小时 | 95%      |
| **有编程基础（3-5 年）** | AI 辅助完成复杂需求 | 2-4 周    | 10-15 小时 | 98%      |
| **零基础**               | AI 辅助完成简单需求 | 4-6 个月  | 15-20 小时 | 70%      |
| **零基础**               | AI 辅助完成中等需求 | 8-12 个月 | 20-25 小时 | 60%      |

#### 知识量估算

**前端方向**：

- HTML/CSS：约 50 个核心概念
- JavaScript：约 100 个核心概念
- 框架（React/Vue）：约 80 个核心概念
- 工程化：约 40 个核心概念
- **总计：约 270 个核心概念**

**后端方向**：

- 语言基础：约 80 个核心概念
- 框架：约 60 个核心概念
- 数据库：约 50 个核心概念
- 部署运维：约 40 个核心概念
- **总计：约 230 个核心概念**

**学习速度**：

- 有编程基础：每周掌握 15-20 个概念
- 零基础：每周掌握 8-12 个概念

### 10.10 关键结论

1. **前端生成代码问题更多在视觉层面**，调试难度更高
2. **后端生成代码问题更多在逻辑和安全层面**，影响更严重
3. **前端写后端可行性高于后端写前端**（85% vs 80% 简单场景）
4. **AI 辅助下，有编程基础者 1-2 个月即可掌握 AI 辅助开发**
5. **零基础需要 6-12 个月才能熟练使用 AI 辅助开发**
6. **调试能力是区分能否独立完成需求的关键**

---

## 十一、参考来源

### 官方网站

- [Claude Code Plugins - Plugin Marketplace](https://claude-plugins.dev/)
- [Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
- [ASL-3 Protections](https://www.anthropic.com/news/activating-asl3-protections)
- [Compliance Framework SB-53](https://www.anthropic.com/news/compliance-framework-SB53)
- [Qoder 官网](https://www.qoder.com/)
- [Qoder 定价](https://qoder.com/pricing)
- [Qoder 文档](https://docs.qoder.com/)
- [Qoder CLI 快速上手](https://docs.qoder.com/zh/cli/quick-start)
- [智谱 AI 开放平台](https://bigmodel.cn/)
- [GLM-4.7 文档](https://docs.bigmodel.cn/cn/guide/models/text/glm-4.7)
- [GLM Coding Plan 定价](https://bigmodel.cn/glm-coding)
- [智谱 AI 定价页面](https://bigmodel.cn/pricing)
- [Cursor 官网](https://cursor.sh/)
- [Claude Code](https://claude.ai/code)

### 模型发布信息

- [GLM-4.7 发布 - 新浪财经](https://finance.sina.com.cn/tob/2025-12-23/doc-inhctxhu0912725.shtml)
- [GLM-4.7 开源 - 开源中国](https://www.oschina.net/news/391481/glm-4-7)
- [GLM-4.6 文档 - 智谱AI](https://docs.bigmodel.cn/cn/guide/models/text/glm-4.6)
- [Claude Opus 4.5 发布 - Anthropic](https://www.anthropic.com/news/claude-opus-4-5)
- [GPT-5.2 发布 - OpenAI](https://openai.com/index/introducing-gpt-5-2-codex/)
- [GPT-5.1-Codex-Max - OpenAI](https://openai.com/index/gpt-5-1-codex-max/)

### 价格与成本分析

- [Qoder 降价信息 - CSDN](https://blog.csdn.net/IRpickstars/article/details/154772522)
- [Qoder 首月 $2 - 阿里云开发者社区](https://developer.aliyun.com/article/1688536)
- [Claude Code 付费完全指南](https://www.cursor-ide.com/blog/claude-code-pricing)
- [Cursor vs Codex vs Claude Code](https://www.cursor-ide.com/blog/cursor-vs-codex-vs-claude-code)
- [2025 AI 工具月度成本分析 - 知乎](https://www.zhihu.com/question/15137704620)

### 重度用户真实案例

- [员工每天花 $1000 用 Claude Code - 腾讯新闻](https://news.qq.com/rain/a/20250614A04FSW00)
- [月烧 35 万元 token，官方连夜限速 - InfoQ](https://www.infoq.cn/article/07mywmhiocsah2m9eqot)
- [用户集体大逃亡！Cursor 自杀式策略 - InfoQ](https://www.infoq.cn/article/06ov3meaqskngp6gm9od)
- [70+ 万一年的 AI 账单 - 网易](https://www.163.com/dy/article/K6UN60JI0511FQO9.html)
- [顶级用户 AI 账单 $10 万/年 - 知乎](https://zhuanlan.zhihu.com/p/1938666160594878863)
- [Cursor 再次调价，包月模式搞不下去了](https://hub.baai.ac.cn/view/49065)
- [12 小时高强度 Claude Code 使用体验 - OneV's Blog](https://onevcat.com/2025/08/claude-code/)

### 产品对比与评测

- [2025 年 AI 编程工具深度对比](https://aicoding.csdn.net/686e3291080e555a88ce5407.html)
- [AI 辅助编程工具深度评测 - 51CTO](https://www.51cto.com/article/817056.html)
- [2025 主流 AI 开发工具对比 - Lewin's Blog](https://lewinblog.com/blog/page/2025/250306-AI-IDEs.md)
- [Claude Code vs Cursor 性价比对比](https://poloapi.com/poloapi-blog/Claude%20is%20the%20king%20of%20cost-effectiveness)

### Qoder CLI 相关

- [Qoder CLI 入门指南 - 知乎](https://zhuanlan.zhihu.com/p/1962499950236632743)
- [阿里发布 Qoder CLI - InfoQ](https://www.infoq.cn/article/t3kbl5pus6watht1huya)
- [使用 Qoder 2 个月经验总结](https://www.cnkirito.moe/qoder-use-guide/)
- [Qoder CLI 社区版部署文档 - 阿里云](https://help.aliyun.com/zh/compute-nest/use-cases/qoder-cli-community-edition-service-instance-deployment-document)
- [Qoder 全栈开发实战指南 - 阿里云开发者社区](https://developer.aliyun.com/article/1687659)

### Qoder 官方文档

- [Qoder 官方文档](https://docs.qoder.com/)
- [Qoder 模型分级选择器](https://docs.qoder.com/zh/user-guide/chat/model-tier-selector)
- [Qoder CLI 使用指南](https://docs.qoder.com/zh/cli/using-cli)
- [Qoder 官网](https://www.qoder.com/)
- [Qoder Repo Wiki 文档](https://docs.qoder.com/zh/user-guide/repo-wiki)
- [Qoder 定价](https://qoder.com/pricing)

### 产品对比与评测

- [阿里Qoder vs Trae vs Cursor：谁才是2025年程序猿的效率之王？ - 知乎](https://zhuanlan.zhihu.com/p/1942632539849200345)
- [Qoder：阿里巴巴推出的AI IDE，全方位了解其能力与未来 - Jimmy Song](https://jimmysong.io/zh/blog/qoder-alibaba-ai-ide-personal-review/)
- [Introducing Cursor 2.0 and Composer - Cursor Blog](https://cursor.com/blog/2-0)
- [Composer: Building a fast frontier model with RL - Cursor Blog](https://cursor.com/blog/composer)
- [阿里Qoder 体验超预期，Repo Wiki 功能迎来全新升级 - InfoQ](https://xie.infoq.cn/article/5e17452ab233d55a2403323ec)
- [从"代码补全"到"知识对齐"：Qoder Repo Wiki 迎来重磅升级 - 阿里云开发者社区](https://developer.aliyun.com/article/1682576)

### 其他

- [无限量供应 Claude，AI IDE 的百亿补贴 - PingWest](https://www.pingwest.com/a/306855)
- [相信大模型成本会下降，是业内最大幻觉 - 知乎](https://zhuanlan.zhihu.com/p/1941285603967742207)
- [Token 成本下降，订阅费却飞涨 - 新浪财经](https://finance.sina.cn/2025-08-06/detail-infizhrw8528637.d.html)

---

**文档更新时间：2025 年 12 月**

**注意**：

1. 价格信息可能随时变动，请以官方公布为准
2. AI 工具的定价策略正在快速变化，建议定期查看官方最新定价
3. 重度用户成本基于真实案例，实际情况可能因使用模式而异

---

## at property

在 CSS 里，`@property` 是一个 **注册自定义属性（CSS Custom Properties）** 的新特性，它解决了原先 `--var: value` 那种“纯字符串变量”的一些缺陷。它主要提供了 **类型约束、初始值、继承控制** 等能力，让浏览器能更高效地处理这些变量，从而带来性能优化。

---

## 1. `@property` 的基本作用

在传统 CSS 里，定义变量只能这样：

```css
:root {
  --main-color: red;
}
```

但浏览器只把它当成字符串，无法提前知道这个变量是“颜色”还是“长度”。这会带来两个问题：

- 无法做类型推断或插值优化（比如动画中间值计算）。
- 每次变量被使用时需要重新解析，性能开销更大。

而 `@property` 可以注册一个有类型的自定义属性：

```css
@property --main-color {
  syntax: '<color>';
  inherits: false;
  initial-value: red;
}
```

这样浏览器就能：

- 知道 `--main-color` 必须是一个颜色；
- 有默认值 `red`；
- 明确是否继承。

---

## 2. 为什么它能优化性能

1. **类型约束 → 加快渲染**
   浏览器不需要把字符串再解析成数值或颜色，而是直接使用已经注册好的类型。

2. **动画性能提升**
   原本 CSS 变量无法参与动画插值，例如：

   ```css
   :root { --size: 10px; }
   div { width: var(--size); transition: width 1s; }
   ```

   这是无效的。但使用 `@property` 注册后，浏览器知道它是 `<length>`，就能平滑插值：

   ```css
   @property --size {
     syntax: '<length>';
     inherits: false;
     initial-value: 10px;
   }
   ```

3. **避免 FOUC/回退渲染**
   有了 `initial-value`，在变量未设置时浏览器不用等到计算阶段才决定默认值，从而减少首次绘制闪烁。

---

## 3. 示例场景

### 动画数值

```css
@property --angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

.box {
  transform: rotate(var(--angle));
  transition: --angle 1s;
}

.box:hover {
  --angle: 360deg;
}
```

👉 盒子会平滑旋转，而不是瞬间跳转。

---

### 渐变颜色

```css
@property --gradient-color {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

.button {
  background: linear-gradient(var(--gradient-color), white);
  transition: --gradient-color 0.5s;
}

.button:hover {
  --gradient-color: red;
}
```

👉 按钮背景色在 hover 时会有渐变过渡。

---

### 响应式尺寸

```css
@property --radius {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.card {
  border-radius: var(--radius);
  transition: --radius 0.3s;
}

.card:hover {
  --radius: 20px;
}
```

👉 hover 时圆角平滑过渡。

---

## 4. 小结

- `@property` 是 **注册型 CSS 自定义属性**。
- 带来性能优化的核心原因：**浏览器能提前知道类型和初始值，减少解析和重绘开销**。
- 实用场景：**动画过渡、主题变量、响应式设计**。

---

确实大多数人提到 `@property` 都会联想到 **transition / animation**，因为这是最直观的刚需。但其实它的用途远不止于动画，这里我给你整理一些 **非动画场景下的“刚需”案例**：

---

## 1. **防止变量未定义时的 FOUC（闪烁）**

普通自定义属性如果没定义，会导致样式不生效甚至回退为 `unset`，页面可能闪烁。
`@property` 可以通过 `initial-value` 提供一个强制的默认值，避免在首次渲染时出现意外。

```css
@property --page-bg {
  syntax: '<color>';
  inherits: true;
  initial-value: white;
}

body {
  background: var(--page-bg);
}
```

👉 即使主题系统的 JS 还没注入 `--page-bg`，页面一开始也会用 **white**，不会闪黑/闪透明。

---

## 2. **保证变量输入合法性**

普通 CSS 变量是字符串，随便写都会被吃掉。
但注册后，浏览器会进行 **语法校验**，错误值会被忽略而回退到 `initial-value`。

```css
@property --spacing {
  syntax: '<length>';
  inherits: false;
  initial-value: 1rem;
}

.card {
  padding: var(--spacing);
}
```

👉 如果有人错误地设置了 `--spacing: "abc";`，不会让布局崩掉，而是安全地回退到 `1rem`。

---

## 3. **在继承/不继承上的精细控制**

普通变量默认会继承，往往带来意料之外的问题。
例如定义主题色时，子元素继承了错误的值。
用 `@property` 就能控制是否继承。

```css
@property --border-color {
  syntax: '<color>';
  inherits: false;
  initial-value: gray;
}

.card {
  border: 1px solid var(--border-color);
}
```

👉 即使父元素设置了 `--border-color: red;`，子元素也不会继承，确保边框始终有稳定表现。

---

## 4. **与容器查询（Container Query）结合**

当你写响应式时，可能用变量去驱动不同尺寸的布局。
如果变量是注册过的，浏览器能更高效地重新计算，而不是“字符串再解析”。

```css
@property --col-gap {
  syntax: '<length>';
  inherits: false;
  initial-value: 1rem;
}

@container (width > 800px) {
  .grid {
    --col-gap: 2rem;
  }
}

.grid {
  display: grid;
  gap: var(--col-gap);
}
```

👉 Gap 会随着容器变化自动稳定更新，而不会因为未定义或错误值导致渲染异常。

---

## 5. **保证动态主题系统更鲁棒**

在“暗黑模式 / 多主题”里，用 `@property` 可以确保每个变量有定义，不会因为缺值导致奇怪的 UI。

```css
@property --theme-accent {
  syntax: '<color>';
  inherits: true;
  initial-value: #0066cc;
}

[data-theme="dark"] {
  --theme-accent: #ffcc00;
}

button {
  color: var(--theme-accent);
}
```

👉 即使某个主题忘了定义 `--theme-accent`，也能回退到默认蓝色，而不是无色。

---

## ✅ 总结

除了 `transition`/`animation`，`@property` 在这些场景也算“刚需”：

1. **提供默认值，避免首屏闪烁**
2. **校验输入合法性，保证健壮性**
3. **控制继承，避免子元素样式污染**
4. **容器查询/响应式布局下提升渲染效率**
5. **多主题系统下保证 fallback 值**

---

## 咨询与定制服务


## 一些碎碎念

国内像我这种开源，大部分都是为爱发电，除了个别朋友零星的打赏之外就再也没有人赞助了，当然打赏的钱也非常少，总的打赏金额比我一天的工资少多了。

诚然，我做开源的目的并不是为了钱，但是，我也知道一个开源项目，想要不断的持续维护，完善下去离不开钱的支持。

就像这个项目已经 `2` 年了，都是我自己维护代码，维护文档，花我自己的钱部署在国内的 `CDN` 上，总的贡献者加我一共 `2` 个人 (截止2024/1/12)，日常维护也只有我一个人。

有些朋友加我，说我文档写的不行，读不懂，那你自己贡献一个易读的版本呀？下面那个编辑此页这么大的 `link` 看到没？

<!-- ## 服务

同时鉴于找我私人咨询和定制开发项目的人越来越多，占用了我很多空余时间。

所以为了解放我自己，我也会对咨询和定制收费:

- 咨询: `200RMB/hour`，一小时起，不包 `100%` 能解决问题
- 定制项目: `2000RMB/day`，一天起，时间由我来进行评估，同样不包 `100%` 能解决问题

另外我定制写的代码，请做好 `code review`，如果产生任何的经济损失，本人概不负责。

所以希望各位小伙伴们，好好看文档，`issue`，以及模板源代码，珍惜各自的时间，好好陪伴你在乎的人。 -->

---

## 加入技术交流群


如果你在使用中遇到什么问题，也欢迎你进入交流群进行提问。

:::tip
添加时请注明来自 `Github: weapp-tw` 项目。
:::

  
    微信群
    微信号 `SonOfMagic`，备注 “weapp-tw”。
    
  

  
    QQ 二群
    扫码加入最新 QQ 技术交流群。
    
  

  
    QQ 一群（已满）
    群号 `49262447` 暂无空位，可等待或加入二群。

---

## 加载自定义字体


## 微信小程序加载自定义字体

详见: https://github.com/sonofmagic/weapp-tailwindcss/discussions/637

---

## cva 与 tailwind-variants 支持

`@weapp-tailwindcss/cva` 与 `@weapp-tailwindcss/variants` 对 `class-variance-authority`（cva）和 `tailwind-variants` 进行了运行时封装，保证输出类名与小程序编译期一致。

:::tip 已迁移到 packages-runtime 体系
详细用法与多端 Demo 请参考：  
- [@weapp-tailwindcss/cva](/docs/community/packages-runtime/cva)  
- [@weapp-tailwindcss/variants](/docs/community/packages-runtime/variants)  
- [@weapp-tailwindcss/variants-v3](/docs/community/packages-runtime/variants-v3)
:::

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/cva
pnpm add @weapp-tailwindcss/variants
```

> 运行时已经内置 `class-variance-authority` / `tailwind-variants`，无需再安装上游依赖。

## cva()

`@weapp-tailwindcss/cva` 直接封装上游 `cva`，并对输出做 escape；返回类型与 `VariantProps` 与原库保持一致。内部带有 256 条短缓存。

```ts

const button = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
  {
    variants: {
      tone: {
        primary: 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]',
        outline: 'border border-border/60 bg-transparent',
      },
      size: {
        sm: 'h-8 px-3',
        md: 'h-9 px-4',
        lg: 'h-10 px-6',
      },
    },
    defaultVariants: {
      tone: 'primary',
      size: 'md',
    },
  },
)

button({ tone: 'outline', size: 'sm' })
// => 已转义类名
```

如需在 Web/H5 端关闭转义，可用 `create`：

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { cva: cvaForWeb } = create({ escape: !isH5, unescape: !isH5 })
```

### Live Demo

```jsx live
function () {
  return <CvaDemo/>
}
```

## tailwind-variants

`@weapp-tailwindcss/variants` 基于 `tailwind-variants`，并默认集成 `@weapp-tailwindcss/merge` 的合并逻辑：

- `tv`：变体工厂（支持 `slots`、`compoundVariants`），返回的类名已转义。
- `cn`：类名聚合器，**返回一个函数**，可选择是否启用 `twMerge`。
- `cnBase`：只拼接并转义，不做合并。
- `createTV`：创建带预设配置的 `tv` 工厂。
- `create`：为多端项目控制 escape/unescape。

### 组合变体

```ts

const badge = tv({
  base: 'inline-flex items-center rounded-full px-2 text-xs font-semibold',
  variants: {
    tone: {
      neutral: 'bg-[#F4F4F5] text-[#18181B]',
      success: 'bg-[#DCFCE7] text-[#166534]',
      danger: 'bg-[#FEE2E2] text-[#B91C1C]',
    },
    soft: {
      true: 'bg-opacity-75',
    },
  },
  compoundVariants: [
    {
      tone: 'danger',
      soft: true,
      class: 'bg-[#F87171] text-white',
    },
  ],
  defaultVariants: {
    tone: 'neutral',
  },
})

badge({ tone: 'success' })
// => 已转义类名
```

### cn / cnBase

```ts

const mergeLater = cn('text-[#ececec]', 'text-[#ECECEC]')
mergeLater() // => 合并 + escape

mergeLater({ twMerge: false }) // => 仅 escape，不合并

cnBase('text-[#ececec]', 'text-[#ECECEC]') // => 仅 escape
```

### 多端项目

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { tv, cn } = create({ escape: !isH5, unescape: !isH5 })
```

### Live Demo

```jsx live
function () {
  return <VariantsDemo/>
}
```

## Tailwind v3 项目

- `tailwindcss@3` ➜ 请使用 `@weapp-tailwindcss/variants-v3`
- Web-only 项目也可直接使用 `tailwind-variant-v3`

---

## 集成与排障指南

:::tip 已迁移到 packages-runtime
运行时包的完整 API 与多端 Demo 已整理在 [packages-runtime](/docs/community/packages-runtime) 章节。
:::

## 与构建工具协作

### 保留关键函数名

`weapp-tailwindcss` 会在编译阶段扫描源码中的 `twMerge`、`twJoin`、`cva`、`cn`、`tv`、`weappTwIgnore` 等标识符。当打包器在压缩环节改写了函数名（如将 `twMerge` 压成 `a`），扫描就会失败，导致运行时字符串无法还原。

- **esbuild / Vite**

  ```ts title="vite.config.ts"
  export default defineConfig({
    build: {
      minify: 'esbuild',
      terserOptions: undefined,
      rollupOptions: {},
    },
    esbuild: {
      keepNames: true,
    },
  })
  ```

- **Terser / Webpack**

  ```js title="webpack.config.js"
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          mangle: {
            keep_classnames: true,
            keep_fnames: true,
          },
        },
      }),
    ],
  },
  ```

完整示例可参考 [`packages/minify-preserve`](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/packages/minify-preserve)。

## 运行时包选择

| Tailwind 版本 | 合并运行时 | 变体运行时 | 说明 |
| --- | --- | --- | --- |
| v4 | `@weapp-tailwindcss/merge` | `@weapp-tailwindcss/variants` | 默认组合，适配 `tailwind-merge@3` |
| v3 | `@weapp-tailwindcss/merge-v3` | `@weapp-tailwindcss/variants-v3` | 旧项目长期维护 |
| v3 Web | `tailwind-variant-v3` | `tailwind-variant-v3` | 仅 Web 场景可直接用上游 |

## 与 weapp-tailwindcss 插件联动

1. **同步依赖版本**：确保 `weapp-tailwindcss` 编译期插件与运行时主版本一致，避免映射表不一致。
2. **配置忽略列表**：如果封装了新的工具函数来代理 `twMerge`/`cva` 等 API，请把这些名称添加到 `ignoreCallExpressionIdentifiers`；模板标签同理使用 `ignoreTaggedTemplateExpressionIdentifiers`。
3. **第三方类名**：需要把类名原样传给第三方库时，用 `weappTwIgnore` 跳过编译期转义。

## rpx 长度与任意值

`@weapp-tailwindcss/merge` 内置 rpx 归一化（例如 `text-[12rpx]` ➜ `text-[length:12rpx]`），避免 `tailwind-merge` 误合并。若你自定义了 rpx 前缀组合，可基于 `createRuntimeFactory` + `createRpxLengthTransform` 构建自定义运行时。

## 调试建议

- **验证运行时版本**：输出 `tailwindMergeVersion`，确认 v3/v4 分支是否正确。
- **确认转义链路**：本地执行脚本，检查 `twMerge` 是否完成「还原 ➜ 合并 ➜ 重新转义」。

  ```bash
  node - <<'NODE'
  const { twMerge } = require('@weapp-tailwindcss/merge')
  console.log(twMerge('text-[#ececec]', 'text-[#ECECEC]'))
  NODE
  ```

- **排查压缩产物**：打包后搜索产物中是否仍然存在 `twMerge`、`weappTwIgnore` 等关键字。
- **快照回归**：对 `twMerge`/`tv` 输出做快照测试，升级 Tailwind 或运行时时便于比对。

---

## 概览

:::tip 已迁移到 packages-runtime
本页为旧入口，内容已按最新源码同步更新；完整体系请参考：  
- [packages-runtime 总览](/docs/community/packages-runtime)  
- [@weapp-tailwindcss/merge](/docs/community/packages-runtime/merge)  
- [多端 Demo（小程序 + Web）](/docs/community/packages-runtime/multi-platform-demos)
:::

`@weapp-tailwindcss/merge` 是面向小程序生态的 `tailwind-merge` 运行时封装，适配 `tailwindcss@4`。它在合并前后自动执行 escape/unescape，并内置 rpx 长度归一化，保证小程序与编译期插件输出保持一致。

## 运行时矩阵

| 包名 | 适用场景 | 说明 |
| --- | --- | --- |
| `@weapp-tailwindcss/runtime` | 共享依赖 | 提供 escape/unescape、`clsx`、`weappTwIgnore`、`createRuntimeFactory` |
| `@weapp-tailwindcss/merge` | `tailwindcss@4` | 基于 `tailwind-merge@3`，默认入口 |
| `@weapp-tailwindcss/merge-v3` | `tailwindcss@3` | 基于 `tailwind-merge@2`，旧项目使用 |
| `@weapp-tailwindcss/cva` | 组件变体 | `class-variance-authority` 运行时封装 |
| `@weapp-tailwindcss/variants` | 组件变体 + slots | `tailwind-variants` 运行时封装 |
| `@weapp-tailwindcss/variants-v3` | v3 小程序 | `tailwind-variant-v3` + `merge-v3` |
| `tailwind-variant-v3` | v3 Web | 上游 v3 runtime，可自定义合并器 |

## 运行时流程（小程序）

`@weapp-tailwindcss/merge` 的默认 `twMerge` 会按以下流程处理：

1. **可选 unescape**：输入包含占位符或 unicode 片段时先还原。
2. **rpx 长度归一化**：`text-[12rpx]` ➜ `text-[length:12rpx]`，避免被合并规则误判。
3. **tailwind-merge 合并**：执行冲突移除。
4. **还原 rpx**：把 `length:` 占位还原回原始写法。
5. **escape 输出**：得到小程序可用的类名。

为了减少重复计算，运行时还内置了短缓存（256 条）。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/merge
```

> 如果项目仍在使用 `tailwindcss@3`，请安装 `@weapp-tailwindcss/merge-v3`。

## 快速上手

```ts

const className = twMerge(
  'px-2 py-1 bg-red hover:bg-dark-red',
  'p-3 bg-[#B91C1C]'
)

// => 已转义的类名，可直接写入小程序 class
```

## rpx 长度归一化

运行时会在合并前把以下前缀的 `rpx` 任意值转换为 `length:` 语义，再在合并后还原：

- `text-*`
- `border-*`
- `bg-*`
- `outline-*`
- `ring-*`

这一步能让 `tailwind-merge` 正确理解 `rpx` 维度，避免误合并。

## 与 weapp-tailwindcss 编译期协作

- `twMerge`、`twJoin`、`cva` 等函数名若被改名，请补充 `ignoreCallExpressionIdentifiers`。
- 需要跳过编译期转义时，使用 `weappTwIgnore` 模板标签：

  ```ts

  const raw = weappTwIgnore`text-[#123456]`
  ```

## 多端项目：按需控制转义

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = false
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})
```

H5 环境将 `isH5` 设为 `true` 即可保持原始类名。

## 相关运行时

- [@weapp-tailwindcss/variants](/docs/community/packages-runtime/variants)
- [@weapp-tailwindcss/cva](/docs/community/packages-runtime/cva)
- [@weapp-tailwindcss/variants-v3](/docs/community/packages-runtime/variants-v3)

## 在线体验

```jsx live
function () {
  return <MergeDemo/>
}
```

---

## 运行时 API

`@weapp-tailwindcss/runtime` 是所有运行时包的公共底座，统一提供 escape/unescape、`clsx`、`weappTwIgnore`、`createRuntimeFactory` 与 `createRpxLengthTransform`。

:::tip 已迁移到 packages-runtime
更完整的使用方式与多端示例已收录在 packages-runtime 章节：  
- [packages-runtime 总览](/docs/community/packages-runtime)  
- [@weapp-tailwindcss/merge](/docs/community/packages-runtime/merge)  
- [@weapp-tailwindcss/variants](/docs/community/packages-runtime/variants)
:::

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/merge
```

如果项目仍在使用 Tailwind CSS v3，请改用 `@weapp-tailwindcss/merge-v3`；而 `@weapp-tailwindcss/runtime` 通常作为间接依赖被自动安装。

## Runtime 基础导出

```ts

  clsx,
  weappTwIgnore,
  resolveTransformers,
  createRuntimeFactory,
  createRpxLengthTransform,
} from '@weapp-tailwindcss/runtime'
```

- `clsx` / `ClassValue`：统一的类名聚合工具，参数类型与 `clsx` 一致。
- `weappTwIgnore`：`String.raw` 的别名，用于跳过编译期转义。
- `resolveTransformers(options?)`：返回 `{ escape, unescape }`，并自动合并默认映射表。
- `createRuntimeFactory(options)`：包装 `tailwind-merge` 等运行时，内置 escape/unescape、短缓存与可插拔的预处理/还原钩子。
- `createRpxLengthTransform(prefixes?)`：提供 `prepareValue`/`restoreValue`，用于 rpx 长度归一化。

## createRuntimeFactory

`createRuntimeFactory` 会把原始 `twMerge`/`twJoin`/`extendTailwindMerge`/`createTailwindMerge` 包装成小程序运行时，内部流程为：

1. 可选 unescape（仅当输入包含占位符时触发）。
2. `prepareValue` 预处理（例如 rpx 归一化）。
3. 原始合并。
4. `restoreValue` 还原。
5. escape 输出并缓存结果（256 条）。

`@weapp-tailwindcss/merge` 与 `merge-v3` 默认使用 `createRpxLengthTransform()` 作为预处理/还原钩子。

## createRpxLengthTransform

默认对以下前缀的任意值进行 rpx 归一化：`text`、`border`、`bg`、`outline`、`ring`。

```ts

const rpxTransform = createRpxLengthTransform(['text', 'bg'])
const create = createRuntimeFactory({
  version: 3,
  twMerge,
  twJoin,
  createTailwindMerge,
  extendTailwindMerge,
  ...rpxTransform,
})
```

## merge 运行时的标准导出

```ts

  twMerge,
  twJoin,
  createTailwindMerge,
  extendTailwindMerge,
  getDefaultConfig,
  mergeConfigs,
  tailwindMergeVersion,
  weappTwIgnore,
  create,
} from '@weapp-tailwindcss/merge'
```

- `@weapp-tailwindcss/merge` 适配 `tailwindcss@4`，`tailwindMergeVersion` 为 `3`。
- `@weapp-tailwindcss/merge-v3` 适配 `tailwindcss@3`，`tailwindMergeVersion` 为 `2`。
- 两个包均内置 rpx 归一化与 escape/unescape，API 完全一致。

## twMerge(...classValues)

合并 Tailwind 工具类并移除冲突项，返回转义后的字符串。支持 `clsx` 兼容的所有参数类型（布尔、数组、对象等）。

```ts
twMerge('px-2 py-1', ['px-6', { 'py-5': shouldExpand }])
// => 'px-6 py-5'
```

## twJoin(...classValues)

拼接类名，不做冲突判断，但仍会走 unescape/escape 与 rpx 归一化流程。

```ts
twJoin('text-[#ececec]', condition && 'bg-[#010101]')
// => 仍会输出转义后的类名
```

## create(options?)

`create` 会基于 `CreateOptions` 返回一组隔离运行时，常用于多端项目控制转义：

```ts
const { twMerge } = create({ escape: false, unescape: false })
```

### CreateOptions

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `escape` | `false` \| `EscapeConfig` | `MappingChars2String` | 控制输出时是否转义；可自定义映射表。 |
| `unescape` | `false` \| `UnescapeConfig` | `MappingChars2String` | 控制合并前是否还原占位符。 |

- 当 `escape`/`unescape` 提供自定义 `map` 时，会与默认映射自动合并。
- `resolveTransformers` 会尽量共享同一映射表，避免编译期与运行时不一致。

## weappTwIgnore

模板字符串标签函数，本质是 `String.raw`，与 `ignoreTaggedTemplateExpressionIdentifiers` 配置联动：

```ts

const raw = weappTwIgnore`
  bg-[#123456]
  before:content-['>']
`
```

## 基于 runtime 的其他包

- `@weapp-tailwindcss/cva`：封装 `class-variance-authority`，详见 [@weapp-tailwindcss/cva](/docs/community/packages-runtime/cva)  
- `@weapp-tailwindcss/variants`：封装 `tailwind-variants`，详见 [@weapp-tailwindcss/variants](/docs/community/packages-runtime/variants)  
- `@weapp-tailwindcss/merge-v3`：面向 `tailwindcss@3` 的长期支持分支  
- `@weapp-tailwindcss/variants-v3`：基于 `tailwind-variant-v3` 的小程序运行时  
- `tailwind-variant-v3`：上游 v3 runtime（Web 优先）

---

## @weapp-tailwindcss/cva

`@weapp-tailwindcss/cva` 是 `class-variance-authority` 的运行时封装，输出的类名会自动完成小程序转义。API 与类型推导保持一致，可直接替换原版 `cva`。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/cva
```

## 基础用法

```ts

const button = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
  {
    variants: {
      tone: {
        primary: 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]',
        outline: 'border border-border/60 bg-transparent',
      },
      size: {
        sm: 'h-8 px-3',
        md: 'h-9 px-4',
        lg: 'h-10 px-6',
      },
    },
    defaultVariants: {
      tone: 'primary',
      size: 'md',
    },
  },
)

type ButtonVariants = VariantProps<typeof button>

const className = button({ tone: 'outline', size: 'sm' })
// => 已转义的类名
```

## 小程序 + Web

使用 `create` 为 Web 关闭转义，保证原始类名：

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { cva: cvaRuntime } = create({
  escape: !isH5,
  unescape: !isH5,
})

const badge = cvaRuntime('text-[#0F172A] bg-[#E2E8F0]')
```

## Demo：跨端变体工厂

```ts

const config = {
  variants: {
    status: {
      ok: 'text-[#16A34A] bg-[#DCFCE7]',
      warn: 'text-[#B45309] bg-[#FEF3C7]',
    },
  },
  defaultVariants: {
    status: 'ok',
  },
}

const pill = cva('inline-flex items-center rounded-full px-2 text-xs font-medium', config)
// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { cva: cvaRuntime } = create({ escape: !isH5, unescape: !isH5 })
const pillWeb = cvaRuntime('inline-flex items-center rounded-full px-2 text-xs font-medium', config)
```

## 常见注意事项

- **函数名别名**：若封装 `cva` 为 `createVariants` 等，请更新 `ignoreCallExpressionIdentifiers`。
- **与 Tailwind 版本关系**：`cva` 不绑定 Tailwind 版本，但 escape 规则需与 `weapp-tailwindcss` 版本一致。

---

## packages-runtime 总览

`packages-runtime` 是 `weapp-tailwindcss` 的运行时能力集合，用来把编译期的类名规则延伸到小程序端，解决「动态类名冲突」「非法字符转义」「多端一致性」等问题。它们基于 `@weapp-tailwindcss/runtime` 提供 escape/unescape 与工厂能力，配合不同的 Tailwind 版本进行组合。

## 运行时矩阵

| 包名 | Tailwind 版本 | 适用场景 | 说明 |
| --- | --- | --- | --- |
| `@weapp-tailwindcss/merge` | v4 | 小程序 / 多端项目 | `tailwind-merge@3` 兼容实现，默认入口 |
| `@weapp-tailwindcss/merge-v3` | v3 | 旧项目 / 长期维护 | `tailwind-merge@2` 兼容实现 |
| `@weapp-tailwindcss/cva` | v3/v4 | 组件变体工厂 | `class-variance-authority` 运行时封装 |
| `@weapp-tailwindcss/variants` | v4 | 组件变体 + slots | `tailwind-variants` 运行时封装 |
| `tailwind-variant-v3` | v3 | Web / 通用 runtime | 上游 v3 runtime，可接入 `twMergeAdapter` |
| `@weapp-tailwindcss/variants-v3` | v3 | 小程序 / 多端 | 基于 `tailwind-variant-v3` + `merge-v3` 的封装 |

> `@weapp-tailwindcss/runtime` 是底座包，通常作为间接依赖自动安装，无需单独引入。

## 版本选择

- **Tailwind v4**：优先 `@weapp-tailwindcss/merge` + `@weapp-tailwindcss/variants`；需要变体工厂时加 `@weapp-tailwindcss/cva`。
- **Tailwind v3**：优先 `@weapp-tailwindcss/merge-v3` + `@weapp-tailwindcss/variants-v3`；仅 Web 或需要定制合并器时可用 `tailwind-variant-v3`。

## pnpm + uni-app 注意事项

uni-app 的 Vite 默认开启 `preserveSymlinks`，会从包内 symlink 路径解析依赖；pnpm 的隔离布局不会把传递依赖放到该路径下，于是会反复出现 “找不到 XXX”（例如 `@vueuse/shared` 是 `@vueuse/core` 的传递依赖）。npm / yarn 不受影响。

想“彻底”解决有两条路：

1. 改 `node-linker` 为 `hoisted`（最彻底，接近 npm/yarn classic）

   在根目录 `.npmrc`（或 `pnpm-workspace.yaml` 的 workspace 配置）中设置后重新 `pnpm install`，依赖会更扁平，`preserveSymlinks` 下也能解析到传递依赖。

   ```ini
   node-linker=hoisted
   ```

2. 保持 `isolated`，持续补 hoist/直依赖（不彻底，维护成本高）

   例如在 `.npmrc` 中追加：

   ```ini
   public-hoist-pattern[]=@weapp-tailwindcss/*
   public-hoist-pattern[]=tailwind-variant-v3
   public-hoist-pattern[]=tailwind-merge
   public-hoist-pattern[]=@weapp-core/*
   ```

   之后遇到新的缺失依赖（如 `@vueuse/shared`）还需要继续补齐为直依赖。

## 多端心智模型（小程序 + Web）

小程序端需要 escape/unescape 来保持类名合法；Web 端则希望保留原始类名。各包的 `create(...)` 工厂允许你为不同端生成隔离实例：

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = false
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})
```

这套模式同样适用于 `cva`、`tv`、`cn` 等变体工具，详见各包的「多端用法」与「多端 Demo」章节。

## 章节速览

- [@weapp-tailwindcss/merge（Tailwind v4）](/docs/community/packages-runtime/merge)
- [@weapp-tailwindcss/merge-v3（Tailwind v3）](/docs/community/packages-runtime/merge-v3)
- [@weapp-tailwindcss/cva](/docs/community/packages-runtime/cva)
- [@weapp-tailwindcss/variants](/docs/community/packages-runtime/variants)
- [tailwind-variant-v3](/docs/community/packages-runtime/tailwind-variant-v3)
- [@weapp-tailwindcss/variants-v3](/docs/community/packages-runtime/variants-v3)
- [多端 Demo：uni-app + Web、Taro + Web](/docs/community/packages-runtime/multi-platform-demos)

---

## @weapp-tailwindcss/merge-v3（Tailwind v3）

`@weapp-tailwindcss/merge-v3` 是 `tailwind-merge@2` 的小程序友好封装，专为 `tailwindcss@3` 设计。API 与 `@weapp-tailwindcss/merge` 完全一致，只是内部合并规则基于 v3 体系。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/merge-v3
```

## 基础用法

```ts

const className = twMerge('p-2 p-4', 'bg-[#0F172A]')
// => 已转义的类名，可直接用于小程序模板
```

## 自定义运行时

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})

twMerge('text-[#2563EB]', 'text-[#1D4ED8]')
// => 'text-[#1D4ED8]'
```

## 与 Tailwind v4 的区别

- `tailwindMergeVersion` 在 v3 入口下为 `2`。
- 仅用于 `tailwindcss@3` 项目；若已升级到 v4，请切换到 [`@weapp-tailwindcss/merge`](./merge)。

## Demo：自定义合并规则

```ts

const mergeSpacing = extendTailwindMerge({
  classGroups: {
    spacing: ['gap-safe', 'gap-huge'],
  },
})

mergeSpacing('gap-huge gap-safe') // => 'gap-safe'
```

---

## @weapp-tailwindcss/merge（Tailwind v4）

`@weapp-tailwindcss/merge` 是 `tailwind-merge@3` 的小程序友好封装，适配 `tailwindcss@4`。它在合并前后自动处理 escape/unescape，使运行时输出与编译期一致。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/merge
```

## 核心 API

- `twMerge(...classValues)`：合并 Tailwind 类名并去冲突。
- `twJoin(...classValues)`：拼接类名（不做冲突判断）。
- `extendTailwindMerge(config)` / `createTailwindMerge(config)`：扩展合并规则。
- `create(options?)`：创建隔离实例，控制 escape/unescape。
- `weappTwIgnore`：标记「不要转义」的模板字符串。

### 基础示例

```ts

const className = twMerge(
  'px-2 py-1 bg-red hover:bg-dark-red',
  'p-3 bg-[#B91C1C]'
)

// => 已转义的类名，可直接写入小程序 class
```

### 扩展合并规则

```ts

const mergeCard = extendTailwindMerge({
  classGroups: {
    card: ['card-default', 'card-primary'],
  },
})

mergeCard('card-default card-primary') // => 'card-primary'
```

## 小程序用法

小程序端建议直接使用默认导出，运行时会自动输出转义后的类名：

```ts

const buttonClass = twMerge(
  'inline-flex items-center rounded-md px-3 py-2 text-sm',
  isPrimary && 'bg-[#2563EB] text-white'
)
```

## Web 用法（关闭转义）

在 Web/SSR 环境中，使用 `create` 关闭 escape/unescape：

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})

const className = twMerge('text-[#2563EB]', 'text-[#1D4ED8]')
// => 'text-[#1D4ED8]'
```

## Demo：按钮类名合并

```ts

const base = 'inline-flex items-center rounded-md px-4 py-2 text-sm font-medium'
const state = 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]'
const override = 'px-6'

const className = twMerge(base, state, override)
```

## 常见注意事项

- **函数名保留**：如果你把 `twMerge` 别名成 `cn`，需要在 `ignoreCallExpressionIdentifiers` 中补充该名称。
- **跳过编译期转义**：当类名需要原样传递给第三方时，用 `weappTwIgnore` 标记模板字符串。

更多细节与调试指南见 [集成与排障指南](/docs/community/merge/integration)。

---

## 多端 Demo：小程序 + Web

本页示例统一以 **Tailwind v4** 为主线（`@weapp-tailwindcss/merge` + `@weapp-tailwindcss/variants`）。如果你的项目仍是 Tailwind v3，请将 `merge/variants` 替换为 `merge-v3/variants-v3`。

## Demo 1：uni-app + Web（Vue + TS）

同一份 `tv` 实例即可覆盖小程序与 H5，通过环境变量决定是否关闭 escape/unescape。

### 共享变体（`src/ui/button.variants.ts`）

```ts

type ButtonConfig = Parameters<ReturnType<typeof create>['tv']>[0]

const config: ButtonConfig = {
  base: 'inline-flex items-center justify-center rounded-md px-3 py-2 text-sm font-medium',
  variants: {
    tone: {
      primary: 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]',
      ghost: 'bg-transparent text-[#0F172A] hover:bg-[#E2E8F0]',
    },
    size: {
      sm: 'h-8 px-3',
      md: 'h-9 px-4',
    },
  },
  defaultVariants: {
    tone: 'primary',
    size: 'md',
  },
}

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
let isH5 = false
// #ifdef H5
isH5 = true
// #endif

const { tv } = create({
  escape: !isH5,
  unescape: !isH5,
})

export const button = tv(config)
```

### 小程序 / H5 共用页面（`src/pages/index/index.vue`）

```vue
<template>
  <view class="p-6 space-y-3">
    <view :class="button({ tone: 'primary' })">Primary</view>
    <view :class="button({ tone: 'ghost', size: 'sm' })">Ghost</view>
  </view>
</template>

<script setup lang="ts">

</script>
```

### 注意事项

- 若你把 `tv`/`cn` 改名封装，请同步更新 `ignoreCallExpressionIdentifiers`。
- H5 端关闭 escape 后，类名保持原样，Tailwind 才能正常匹配。

## Demo 2：Taro + Web（React + TSX）

同一份 `tv` 实例即可覆盖小程序与 H5，通过环境变量决定是否关闭 escape/unescape。

### 共享变体（`src/ui/card.variants.ts`）

```ts

type CardConfig = Parameters<ReturnType<typeof create>['tv']>[0]

const config: CardConfig = {
  base: 'rounded-xl border border-[#E2E8F0] bg-white p-4 shadow-sm',
  variants: {
    tone: {
      normal: 'text-[#0F172A]',
      muted: 'text-[#64748B] bg-[#F8FAFC]',
    },
  },
  defaultVariants: {
    tone: 'normal',
  },
}

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = process.env.TARO_ENV === 'h5'
const { tv } = create({
  escape: !isH5,
  unescape: !isH5,
})

export const card = tv(config)
```

### 小程序页面（`src/pages/index/index.tsx`）

```tsx

export default function Index() {
  return (
    <View className={card({ tone: 'normal' })}>
      <Text>Card for Mini Program</Text>
    </View>
  )
}
```

### Web 组件（`src/components/Card.web.tsx`）

```tsx

export function CardWeb() {
  return Card for Web
}
```

### 注意事项

- `process.env.TARO_ENV` 在构建期注入，适用于 H5/小程序的条件切换。
- 若你使用 Tailwind v3，请切换为 `@weapp-tailwindcss/variants-v3`。

## 扩展方向

- 用 `compoundVariants` 或 `slots` 增强可复用组件。
- 为 `cn` 设置 `twMerge: false`，在需要保留全部类名的场景禁用合并。
- 将多端配置封装为 `createVariantsRuntime()`，统一团队用法。

---

## tailwind-variant-v3

`tailwind-variant-v3` 是 Tailwind v3 时代的变体运行时（上游包），提供 `tv`/`createTV`/`cn` 等 API，并支持通过 `twMergeAdapter` 接入自定义合并器。它不包含小程序的 escape/unescape 逻辑。

## 安装

```bash npm2yarn
pnpm add tailwind-variant-v3 tailwind-merge@^2
```

## 基础用法

```ts

const button = tv({
  base: 'inline-flex items-center rounded-md px-3 py-2 text-sm',
  variants: {
    tone: {
      primary: 'bg-blue-600 text-white',
      ghost: 'bg-transparent text-zinc-900',
    },
  },
  defaultVariants: {
    tone: 'primary',
  },
})

const className = button({ tone: 'ghost' })
const merged = cn('text-zinc-900', 'text-zinc-700')({ twMerge: true })
```

## 默认 twMerge 配置

```ts

const { cn, tv } = create({
  twMergeConfig: {
    extend: {
      classGroups: {
        'font-size': [{ text: ['20', '22', '24', '26', '28', '30', '32'] }],
      },
    },
  },
})

cn('text-32', 'text-surface-700')()
tv({ base: 'text-32 text-surface-700' })()
```

## 小程序适配：注入 merge-v3

如果你希望在小程序端使用 `tailwind-variant-v3`，可以通过 `twMergeAdapter` 接入 `@weapp-tailwindcss/merge-v3`：

```ts

const adapter: TailwindMergeAdapter = { twMerge, extendTailwindMerge }

const badge = tv(
  {
    base: 'inline-flex items-center rounded-full px-2 text-xs',
  },
  {
    twMergeAdapter: adapter,
  },
)
```

> 如果你主要面向小程序，推荐使用 `@weapp-tailwindcss/variants-v3`，它会自动处理 escape/unescape。

## 适用场景建议

- **Web / SSR**：直接使用 `tailwind-variant-v3`。
- **小程序**：优先使用 [`@weapp-tailwindcss/variants-v3`](./variants-v3)。

---

## @weapp-tailwindcss/variants-v3

`@weapp-tailwindcss/variants-v3` 是 `tailwind-variant-v3` 的小程序封装，内置 `@weapp-tailwindcss/merge-v3`，自动完成 escape/unescape 与类名合并。适用于 `tailwindcss@3` 项目。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/variants-v3
```

## tv：变体工厂

```ts

const tag = tv({
  base: 'inline-flex items-center rounded-full px-2 text-xs font-medium',
  variants: {
    tone: {
      neutral: 'bg-[#F4F4F5] text-[#18181B]',
      success: 'bg-[#DCFCE7] text-[#166534]',
    },
  },
  defaultVariants: {
    tone: 'neutral',
  },
})

tag({ tone: 'success' }) // => 已转义类名
```

## cn / createTV

```ts

const mergeLater = cn('text-[#ececec]', isActive && 'text-[#ECECEC]')
mergeLater() // => 合并 + escape

const tvBase = createTV({ twMerge: false })
```

## 小程序 + Web

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { tv } = create({
  escape: !isH5,
  unescape: !isH5,
})

const card = tv({
  base: 'rounded-xl border border-[#E2E8F0] bg-white',
})
```

## Demo：复用同一配置

```ts

const config = {
  base: 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium',
  variants: {
    tone: {
      primary: 'bg-[#2563EB] text-white',
      danger: 'bg-[#DC2626] text-white',
    },
  },
  defaultVariants: {
    tone: 'primary',
  },
}

const button = tv(config)
// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { tv: tvRuntime } = create({ escape: !isH5, unescape: !isH5 })
const buttonWeb = tvRuntime(config)
```

## 默认 twMerge 配置

```ts

const { cn, tv } = create({
  twMergeConfig: {
    extend: {
      classGroups: {
        'font-size': [{ text: ['20', '22', '24', '26', '28', '30', '32'] }],
      },
    },
  },
})

cn('text-32', 'text-surface-700')()
tv({ base: 'text-32 text-surface-700' })()
```

## 常见注意事项

- **Tailwind v4**：请改用 [`@weapp-tailwindcss/variants`](./variants)。
- **Web-only 项目**：可直接使用 `tailwind-variant-v3`。

---

## @weapp-tailwindcss/variants

`@weapp-tailwindcss/variants` 是 `tailwind-variants` 的小程序封装，自动完成 escape/unescape，并默认集成 `@weapp-tailwindcss/merge` 的合并能力。适用于 Tailwind v4 项目。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/variants
```

## tv：变体工厂

```ts

const button = tv({
  base: 'inline-flex items-center gap-2 rounded-md text-sm font-medium transition-colors',
  slots: {
    icon: 'size-4',
    label: 'truncate',
  },
  variants: {
    tone: {
      primary: 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]',
      ghost: 'bg-transparent text-[#0F172A] hover:bg-[#E2E8F0]',
    },
    size: {
      sm: { base: 'h-8 px-3', icon: 'size-3' },
      md: { base: 'h-9 px-4', icon: 'size-4' },
    },
  },
  defaultVariants: {
    tone: 'primary',
    size: 'md',
  },
})

const slots = button({ tone: 'ghost', size: 'sm' })
slots.base() // => 已转义类名
slots.icon({ class: 'text-xs' })
```

## cn / cnBase

```ts

const mergeLater = cn('text-[#ececec]', isActive && 'text-[#ECECEC]')
mergeLater() // => 合并 + escape

mergeLater({ twMerge: false }) // => 仅 escape，不合并
```

## 小程序 + Web

```ts

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { tv, cn } = create({
  escape: !isH5,
  unescape: !isH5,
})

const card = tv({
  base: 'rounded-xl border border-[#E2E8F0] bg-white',
})

const className = cn('text-[#0F172A]', 'text-[#1E293B]')()
```

## Demo：复用同一配置

```ts

const buttonConfig = {
  base: 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium',
  variants: {
    tone: {
      primary: 'bg-[#2563EB] text-white',
      danger: 'bg-[#DC2626] text-white',
    },
  },
  defaultVariants: {
    tone: 'primary',
  },
}

const button = tv(buttonConfig)
// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { tv: tvRuntime } = create({ escape: !isH5, unescape: !isH5 })
const buttonWeb = tvRuntime(buttonConfig)
```

## 默认 twMerge 配置

```ts

const { cn, tv } = create({
  twMergeConfig: {
    extend: {
      classGroups: {
        'font-size': [{ text: ['20', '22', '24', '26', '28', '30', '32'] }],
      },
    },
  },
})

cn('text-32', 'text-surface-700')()
tv({ base: 'text-32 text-surface-700' })()
```

## 常见注意事项

- **函数名保留**：`tv`/`cn` 若被改名，需要配置 `ignoreCallExpressionIdentifiers`。
- **Tailwind v3**：请改用 [`@weapp-tailwindcss/variants-v3`](./variants-v3)。

---

## 适配的 `tailwindcss` 插件


虽然，相当一部分 `tailwindcss` 插件，都可以直接在 `weapp-tailwindcss` 里使用了。

但是小程序中 `wxss` 这种 `css` 子集，是原生不支持许多 `css` 的写法和选择器的，所以免不了在使用某些插件的时候会报错。

比如 `tailwindcss/typography`, `daisyui` 等等。

所以很多时候开发它们的迁移/阉割版本是不可避免。

比如 `tailwindcss/typography` 的小程序适配版本就是 `@weapp-tailwindcss/typography`

而 [`IceStack`](https://ui.icebreaker.top/zh-CN/docs/usage) 内部也包含了 `daisyui` 的微信小程序适配。

---

## @weapp-tailwindcss/reset


`@weapp-tailwindcss/reset` 是一个独立的 reset 资源包，适合在 `uni-app` / `Taro` 项目的入口样式中直接导入，也可以直接作为 Tailwind 插件使用。

它现在同时提供两类能力：

- 静态样式文件集合，直接 `import '@weapp-tailwindcss/reset/xxx.css'`
- Tailwind 插件入口，通过 `reset({...})` 或 `@plugin` 注入 base 规则

为了兼容旧项目，[`weapp-tailwindcss/reset`](/docs/options/reset) 仍然保留导出；但新的插件实现本体已经迁到 `@weapp-tailwindcss/reset`。

## 安装

```bash
pnpm add -D @weapp-tailwindcss/reset
```

## 当前提供的 reset

| 路径 | 说明 | 适用场景 |
| --- | --- | --- |
| `button-after.css` | 清理 `button::after` 默认样式 | 需要更自由地改按钮边框时优先引入 |
| `normalize.css` | `normalize.css` 的跨端静态版本 | 偏保守、接近浏览器默认行为 |
| `modern-normalize.css` | `modern-normalize` 的跨端静态版本 | 想要更现代、轻量的基线 |
| `eric-meyer.css` | 经典 Eric Meyer reset | 需要强 reset、自己完全接管基础样式 |
| `sanitize/sanitize.css` | `sanitize.css` 主体规则 | 更强调可访问性与默认安全值 |
| `sanitize/assets.css` | `sanitize.css` 的资源尺寸约束补充 | 与上面配套使用 |
| `tailwind.css` | 静态版 Tailwind preflight | 想直接拿 Tailwind 风格 reset |
| `tailwind-compat.css` | 移除按钮背景色重置的 Tailwind preflight | 和组件库一起使用时更稳妥 |

## 作为 Tailwind 插件使用

```ts

export default {
  plugins: [
    reset({
      preset: 'all',
      listReset: false,
    }),
  ],
}
```

插件默认保持兼容旧行为，只注入 `button` 和 `image`。如果你希望批量打开更多内置 reset，可以使用：

- `preset: 'form'`
- `preset: 'content'`
- `preset: 'media'`
- `preset: 'all'`

可额外控制的内置 reset 包括：

- `inputReset`
- `textareaReset`
- `listReset`
- `navigatorReset`
- `videoReset`

如果你已经在项目里使用 `weapp-tailwindcss/reset`，无需迁移；两者行为保持一致，只是实际实现现在归属到这个包。

## uni-app 用法

通常在 `src/main.ts`、`App.vue` 或全局入口样式中导入：

```ts

```

如果你使用 `sanitize.css`，通常要把两个文件一起引入：

```ts

```

## Taro 用法

通常在 `src/app.tsx` 或入口样式中导入：

```ts

```

## 选择建议

- 项目里已经用了组件库，优先 `button-after.css + tailwind-compat.css`
- 想接近 Tailwind 默认 preflight，选 `tailwind.css`
- 想保守一点，选 `modern-normalize.css` 或 `normalize.css`
- 想强力清空默认样式，选 `eric-meyer.css`
- 想要更完整的默认安全值和资源约束，选 `sanitize/sanitize.css + sanitize/assets.css`

## 典型组合

```ts

```

上面这组通常适合有组件库的项目。

```ts

```

上面这组通常适合只想补一个轻量全局基线的项目。

## 与主包样式的关系

`@weapp-tailwindcss/reset` 不会替代 `weapp-tailwindcss/index.css`、`preflight.css` 这些主包产物。它更像一个“可选 reset 仓库”，让你在入口处自行决定要引哪一套基线样式。

如果你已经在用 `weapp-tailwindcss/index.css`，是否还要额外引入这里的 reset，需要根据你的项目基线和组件库兼容性决定，不建议无脑叠加多套 reset。

---

## 🔥各个框架的模板


当你配置不对的时候，也可以参考参考, 其中带有 🔥 标志的为推荐使用版本

:::tip
假如你遇到网络问题，无法登陆 `Github` 的时候，你可以使用 `Gitee`。

登陆进 `Gitee` 之后，点击右上角的加号，有一个导入仓库功能。然后你想使用什么模板，你就右键下方模板的link，点击复制链接地址，然后把复制的url，粘贴到`Gitee`导入仓库的 `Git Repository URL` 中去，点击确定导入之后，过几秒仓库就能够同步完成，就可以下载了。
:::

## uni-app

---

### 使用 `uni-app cli` 进行构建 `vscode` 开发

<TemplateLink
  hot
  title="uni-app-vite-vue3-tailwind-vscode-template"
  href="https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="uni-app-vite-vue3-tailwind-vscode-template"
/>

<TemplateLink
  title="uni-app-vue2-tailwind-vscode-template"
  href="https://github.com/sonofmagic/uni-app-vue2-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="uni-app-vue2-tailwind-vscode-template"
/>

<TemplateLink
  title="monorepo-uniapp-template"
  href="https://github.com/sukbearai/x-dev-uni"
  repoOwner="sukbearai"
  repo="x-dev-uni"
/>

{/* ### 若依移动端 (`hbuilderx` 集成 `tailwindcss`)

<TemplateLink
  hot
  title="若依移动端"
  description="Gitee 地址"
  href="https://gitee.com/sonofmagic/RuoYi-App"
/> */}

### 使用 `hbuilderx` 进行构建和开发

<TemplateLink
  title="uni-app-vue3-tailwind-hbuilder-template"
  href="https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template"
  repoOwner="sonofmagic"
  repo="uni-app-vue3-tailwind-hbuilder-template"
/>

<TemplateLink
  deprecated
  title="uni-app-vue2-tailwind-hbuilder-template"
  description="架构太过老旧，只能作为集成参考，新项目请勿使用"
  href="https://github.com/icebreaker-template/uni-app-vue2-tailwind-hbuilder-template"
  repoOwner="icebreaker-template"
  repo="uni-app-vue2-tailwind-hbuilder-template"
/>

## tarojs

---

### 使用 `tarojs` 进行构建 `vscode` 开发

<TemplateLink
  hot
  title="taro-react-tailwind-vscode-template"
  href="https://github.com/sonofmagic/taro-react-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="taro-react-tailwind-vscode-template"
/>

## native

---

### 原生小程序开发模板

<TemplateLink
  hot
  title="weapp-vite-tailwindcss-template"
  description="weapp-vite 打包"
  href="https://vite.icebreaker.top/guide/"
/>

<TemplateLink
  title="vue-mini-tailwindcss-template"
  description="vue-mini 支持"
  href="https://github.com/sonofmagic/vue-mini-tailwindcss-template"
  repoOwner="sonofmagic"
  repo="vue-mini-tailwindcss-template"
/>

#### 下方的技术架构过于老旧，不推荐

<TemplateLink
  deprecated
  title="native-weapp-tailwindcss-template"
  description="cli 打包"
  href="https://github.com/sonofmagic/native-weapp-tailwindcss-template"
  repoOwner="sonofmagic"
  repo="native-weapp-tailwindcss-template"
/>

<TemplateLink
  deprecated
  title="weapp-tailwindcss-gulp-template"
  description="gulp 打包"
  href="https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/gulp-app"
/>

## `tailwindcss@4`

所有的 `tailwindcss@4` 模板都维护在下方的地址，标志为标题带有 `tailwindcss-v4` 字样:

https://github.com/icebreaker-template

## 更多模板

你还可以在项目的根目录的 `demo` 文件夹中，找到各个框架的注册方式。

里面有 `gulp` , `mpx` , `webpack5` , `rax` , `taro-react` , `taro-vue2` , `taro-vue3` , `uni-app vue2 webpack5` , `uni-app vue3 vite` 的项目

---

## @weapp-tailwindcss/typography


小程序 `@tailwindcss/typography` 富文本渲染方案

`@weapp-tailwindcss/typography` 是 `@tailwindcss/typography` 的小程序迁移版本，帮助你渲染美丽的富文本。

<iframe src="//player.bilibili.com/player.html?aid=751356751&bvid=BV16k4y1S7nY&cid=1408037969&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

## 介绍

在小程序中，我们往往使用 [rich-text](https://developers.weixin.qq.com/miniprogram/dev/component/rich-text.html) 组件，然后从后端请求到 `html` 字符串片段，然后放到小程序中去渲染，所示:

```html
<rich-text nodes="{{nodes}}"></rich-text>
```

但是，使用它有很多的限制，比如自定义组件中使用 `rich-text` 组件，那么仅自定义组件的 `wxss` 样式对 `rich-text` 中的 `class` 生效。

所以针对这种 `case` 设计了 `@weapp-tailwindcss/typography` 来解决小程序渲染富文本的问题。

## 如何使用?

### 安装

```sh npm2yarn
npm i -D @weapp-tailwindcss/typography
```

### 注册

这里比较特殊，由于`rich-text` 组件的样式限制: 自定义组件中使用 `rich-text` 组件，那么仅自定义组件的 `wxss` 样式对 `rich-text` 中的 `class` 生效

#### 创建组件

这里以 `uni-app vue3 vite` 项目为例，比如此时我们目标组件为 `typography.vue`:

```html
<template>
  <rich-text class="prose" :nodes="nodes"></rich-text>
</template>

<script lang="ts" setup>
// getHtml 为你获取 html 的方法

const nodes = transform(getHtml())
</script>

<style>
@config "./tailwind.typography.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

#### 创建独立 tailwindcss 上下文

在当前 `typography.vue` 组件目录下，单独创建一个 `tailwind.typography.config.js` 来创建独立的 `tailwindcss` 上下文，单独处理它，

```js
const path = require('node:path');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [path.resolve(__dirname, './typography.vue')],
  plugins: [require('@weapp-tailwindcss/typography')],
  corePlugins: {
    preflight: false,
  },
};
```

此时渲染 `html` 就生效了。

#### 指定全局样式配置文件

但是这还没有结束，为了防止这个上下文，影响到你全局的 `tailwindcss` 上下文，你必须做一个显式指定。

此时要在你的引入 `tailwindcss` 的入口文件处(`App.vue`)，声明它用的是根目录的 `tailwind.config.js`

```css
@config "../tailwind.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
```

这样配置才最终完成。

> 使用 @import 要注意加载顺序是不同的，详见 <https://tailwindcss.com/docs/functions-and-directives#config>

## 配置项

大体的配置项与 <https://tailwindcss.com/docs/typography-plugin> 是相同的

额外添加了 `mode` 和 `classPrefix`

## 原理解释

`@weapp-tailwindcss/typography/transform` 这个方法是为你的 `html` 所有的元素给大上 `class` 属性，这样才能使用那些 `prose-headings:bg-red-100`,`prose-h5:text-green-400` 的写法，来覆盖原先富文本的样式。

而 `@weapp-tailwindcss/typography` 通过 `mode` 的配置，`mode` 为 `tag` 表示为原先默认的行为，`mode` 为 `class`，此时插件更改为对所有的 `class` 选择器生效，而不是对所有的标签生效。默认值为 `class`

假如你觉得 `@weapp-tailwindcss/typography/transform` 放在小程序端处理，体积太大了，你可以把它放在 `nodejs` 服务中，预先处理。

## Demo

<https://github.com/sonofmagic/weapp-tailwindcss/blob/main/demo/uni-app-vue3-vite/src/pages/issue/typography.vue>

---

## 生态以及解决方案


## 插件

### [@weapp-tailwindcss/typography](./community/typography)

### [@weapp-tailwindcss/reset](./community/reset)

### [开箱即用的小程序icon解决方案](./icons)

### [uni-app 条件编译语法糖插件](./quick-start/uni-app-css-macro)

## 模板

### [各个框架的模板](./community/templates)

## 解决方案

### [小程序多主题方案](./quick-start/apply-themes)

### [构建以及引入外部组件](./quick-start/build-or-import-outside-components)

### [tailwindcss 多上下文与独立分包](./quick-start/independent-pkg)

### [wxs的转义与处理](./quick-start/wxs)

## 社群

### [加入技术交流群](./community/group)

<!-- ### [咨询与定制服务](./community/consult) -->

---

## 版权信息

## AtomGit G-Star 项目毕业认证

  
    
  

## 软件著作权登记证书

---

## 技术演进


目前 `weapp-tailwindcss` 使用:

- `babel` 来处理 `js`/`wxs`
- `htmlparser2` 来处理 `wxml`
- `postcss` 来处理 `wxss`

## wxml

使用 `htmlparser2` 已经是 `v2` 版本后期的事情了

一开始使用的是 `@vivaxy/wxml` 这是一个 `wxml` 的 `ast` 工具

但是它已经很久没有更新了，在遇到内联的 `wxs` 的时候，会直接挂掉

后续使用正则来出来，但是 正则 同样是有问题的，比如这样一个 case:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会提前匹配并进行返回，所以还是要使用 `ast` 工具才能做到精确。

而 `parse5` 对 html5 是严格的匹配，不怎么适用于 wxml

所以最终选择 `htmlparser2` 来处理 `wxml`

## babel

这里主要有1个演进原先是

`@babel/parser`->`@babel/traverse`->`@babel/generator`

但是这样，相当于重新生成了一遍用户的 js，同时 sourcemap 也会错乱

所以后续改成了 `@babel/parser`->`@babel/traverse`->`magic-string#replace` 的方式，做精确匹配

## postcss

这里的演进比较多，也就是相当于加入了多个 postcss 插件进行转换。

---

## 如何贡献


> 推荐阅读 [如何为开源做贡献?](https://opensource.guide/zh-hans/how-to-contribute/)

## 如何本项目做贡献？

其实非常简单，你不一定需要贡献代码，你提一个 `issue`，回答一个问题，写一篇相关的文章，这些都是为项目做贡献，无需拘泥于具体的形式。

无论你做什么，只要你对这个项目的发展，起到正向的帮助的，我们对你表示感谢 🙏！

## 贡献指南

首先，你必须 `fork` [`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss) 这个项目到你自己的账号下，然后你再把它 `git clone` 到你的本地。

### 文档贡献

目前本网站所有的文档都在 [weapp-tailwindcss/website](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/website) 目录下，

你可以在里面任意添加文章，修改文章，删除文章，然后提交到你 `fork` 的分支，然后在 `pr` 到 `weapp-tailwindcss` 的 `main` 分支。

`website` 这个项目会被部署到 `https://tw.icebreaker.top` 这个域名下，作为 [`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss) 的文档展示。

就项目而言，这是一个 `docusaurus@2` 的项目，和 `vuepress`/`vitepress` 类似，它也是一个开源的文档生成工具，不过它是 `react` 写的。

> `docusaurus` 相关的文档见 [docusaurus.io](https://docusaurus.io/)

#### 目录介绍

- `docs`: `md`,`mdx` 文档所在位置
- `src`: 源代码，你可以在这里写 `jsx`,`tsx`
- `static`: 静态资源所在位置
- `docusaurus.config.js`: `docusaurus` 配置，可在此处调配 `navbar`
- `sidebars.js`: 调整所有 `sidebar` 的配置文件，当你添加一篇文档，你需要在这里声明它的位置

### 代码贡献

#### 根目录介绍

- `assets`: 存放所有静态资源的地方，包括 `weapp-tailwindcss` 所有的 `logo`，还有对应的 `figma` 文件可以做二次设计开发
- `bin`: `cli` 入口文件
- `demo`: 存放所有 `demo` 的地方，里面包含各个框架的各种使用方式
- `demo-linked`: 存放部分 `demo` 的地方，不同的是，这里 `weapp-tailwindcss` 的注册方式都是本地 `linked`
- `e2e`: 存放 `e2e` 测试的地方，测试对象就是 `demo` 下的那些项目
- `plugins`: 存放一些从 `web` 迁移到小程序的 `tailwindcss` 插件，目前包含 `@weapp-tailwindcss/typography`
- `scripts`: 存放一些常用脚本的位置，比如 `readme.md` 生成脚本等等
- `src`: 源代码目录，待会细讲
- `test`: 单元测试和测试快照位置，一般出现一个 `bug`，我们都需要设计 1 到多个测试用例，测试通过后才能发布
- `website`: 文档网站

#### 使用技术介绍

- 单元测试和 `e2e` 测试现在完全使用了 `vitest` 过去曾经是 `jest`
- 打包使用的是 `rollup`

### src 源代码介绍

目前 `weapp-tailwindcss` 使用:

- `babel` 来处理 `js`/`wxs`
- `htmlparser2` 来处理 `wxml`
- `postcss` 来处理 `wxss`

Why？

#### wxml htmlparser2

使用 `htmlparser2` 已经是 `v2` 版本后期的事情了

一开始使用的是 `@vivaxy/wxml` 这是一个 `wxml` 的 `ast` 工具

但是它已经很久没有更新了，在遇到内联的 `wxs` 的时候，会直接挂掉，另外还有各种问题。

后续使用正则来处理 `wxml`，但是正则同样是有问题的，比如这样一个 `case`:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会提前匹配并进行返回，所以还是要使用 `ast` 工具才能做到精确。

而 `parse5` 对 `html5` 是严格的匹配，不怎么适用于 `wxml`

所以最终选择 `htmlparser2` 来处理 `wxml`

#### js/wxs babel

这里主要有1个演进原先是

`@babel/parser`->`@babel/traverse`->`@babel/generator`

但是这样，相当于重新生成了一遍用户的 js，同时 sourcemap 也会错乱

所以后续改成了 `@babel/parser`->`@babel/traverse`->`magic-string#replace` 的方式，做精确匹配

#### postcss

这里的演进比较多，也就是相当于加入了多个 postcss 插件进行转换。

### src 目录介绍

- `babel`: `babel` 工具类
- `bundlers`: 存放使用方式，目前提供 `webpack`,`vite`,`gulp` 插件的使用方式
- `cache`: 缓存策略，用于解决在项目比较大时，热更新的速度问题，本质上是通过计算文件内容的 `hash` 值，如果没有发生改变就跳过 `ast` 的解析，直接返回结果的策略
- `css-macro`: `uni-app` 样式条件编译插件
- `debug`: `debug` 调试用
- `extractors`: 提取器，用于分割字符串
- `js`: 用于处理转译 `js` 结果的地方
- `postcss`: 和 `postcss` 相关，用于处理所有 `wxss` 结果的地方
- `tailwindcss`: 用于 `hack` `tailwindcss`，给它打补丁，强制让它支持小程序的一些特性
- `wxml`: 处理 `wxml` 的地方
- `*`: `src` 其他一些文件，大多是一些导出文件

想要知道各自做了什么事情，详见 [深入核心原理](./principle)

## 如何本地调试

你是否对我这种类型项目的本地调试感到棘手？

其实本地调试很简单，你怎么调试 `webpack`/`vite`/`gulp`/`postcss`插件，同样可以用这些的经验来调试这个项目。

### 单元测试调试

目前这个项目里有大量的单元测试，来对各个模块进行测试。

目前我使用的使用 `vitest` 来进行进行单元测试 (之前使用 `jest` + `ts-jest` 但是它对 `esm`+`cjs`的混合引用的模式，支持不算很好)

所以你可以安装 `vscode` 的 `vitest` 插件，安装完成之后，在 `vscode` 左侧的测试管理器会看到大量的测试用例，这些都是它感应到了 `test` 项目里的单元测试。

此时，你可以选中一个，你就可以进行 `运行`，或者 `调试` ，或者 `打开测试文件` 的操作。

当然你也可以直接打开 `*.test.ts` 测试文件，此时，在 `describe`/`test`/`it` 在前面会出现一个运行的绿色 `icon`，直接点是 `运行`，右键选择 `调试测试` 即可

比如你要调试我的 `postcss` 插件，你就可以引用我的相关代码，在 `test` 文件里写一个用例：

比如 `console.log` 一下 `postcss([plugin]).process(rawSource).css` 结果 ，然后在我的 `postcss` 源代码里面打上断点，这时候再去进行 `调试` 操作，就能命中源码里面的断点了。

调试 `webpack`/`vite` 等等插件同理，你需要准备 `webpack`/`vite` 对应的配置,比如 `webpack/vite` 的 `api` 去引入插件，来进行构建，这样才能命中插件里的断点。

## 源码映射调试

这里的核心是 `sourcemap`，你需要在本地构建的时候，把 `sourcemap` 打出来，然后把所有产物被对应的 `app` 应用（`uni-app`/`taro`）引入并注册

这样你在使用 `javascript` 调试终端，进行运行的时候，就能命中 `dist` 产物里的 `js`，然后再根据 `sourcemap` 命中到你的 `ts` 源码里去了。

当然，假如你生成的 `sourcemap` 不对，或者不生成，你也可以直接在 `dist` 产物里的 `js` 直接打断点进行调试，不过这需要你对源代码比较了解。

当然，每次都使用 `javascript` 调试终端太过于麻烦，为此我准备了 `.vscode/launch.json` 文件，帮助我们快速进行框架产物调试，这样才能获取第一手的 `uni-app` / `taro` 产物。

---

## 小程序 `icon` 解决方案


这里介绍一种在小程序里，开箱即用的 icon 解决方案：[`iconify`](https://iconify.design/)

很高兴，我们已经有这样的能力，为小程序提供大量的 `icon`, 供我们开发者自己进行选择。

## 立即开始

首先，在已经安装和配置完本插件之后，安装 [`@egoist/tailwindcss-icons`](https://www.npmjs.com/package/@egoist/tailwindcss-icons)

```sh npm2yarn
npm i -D @egoist/tailwindcss-icons
```

:::tip
**Iconify for Tailwind CSS** 其实给我们提供了两种选择：
`@iconify/tailwind` 和 `@egoist/tailwindcss-icons`

个人用下来，感觉 `@egoist/tailwindcss-icons` 更好用一点，智能提示也更好一些。

因为它是直接把全部的 `icon` 生成在 `components` 里, 然后再交给 `Tailwind CSS` 从里面进行挑选再输出到我们的 `css` 文件中的。

而 `@iconify/tailwind` 走的是 `jit` 动态加载生成，但是没有智能提示加 `` 不好用啊，笑～。

详见 <https://iconify.design/docs/usage/css/tailwind/>
:::

然后在 `tailwind.config.js` 注册插件:

```js
const { iconsPlugin, getIconCollections } = require("@egoist/tailwindcss-icons")

module.exports = {
  plugins: [
    iconsPlugin({
      // Select the icon collections you want to use
      collections: getIconCollections(["mdi", "lucide"]),
    }),
  ],
}
```

然后你还要安装你挑选的 `icon` 集合包，比如你选择了 `"mdi"` 和 `"lucide"`

那你就要安装: `@iconify-json/mdi` 和 `@iconify-json/lucide` (包名的规则就是：`@iconify-json/{collection_name}`)

当然你也可以直接安装 `@iconify/json`，这里面包含了所有的 `icon`,不过代价就是，这个包比较大（50MB+）

然后你回到你的页面，输入 `i-` 智能提示就出来了，然后就可以这么写了：

`<view class="i-mdi-home text-3xl text-red-600"></view>`

> 假如不起作用，`Tailwindcss@3` 的话，请检查你的 `@tailwind components;` / `@import 'tailwindcss/components';`(scss) 是否在入口 `css/scss` 中引入

## Tailwindcss v4

在 `Tailwindcss@4` 中，不会自动读取 `tailwind.config.js` 文件，所以你需要使用 [@config](https://tailwindcss.com/docs/functions-and-directives#config-directive) 指令，手动 引入 `tailwindcss` 的配置文件。

```css
@import "tailwindcss";
/* 添加下面这一行，路径为你创建的 tailwind.config.js 文件路径 */
/* highlight-next-line */
@config "../tailwind.config.js";
```

> **注意**：实际运行时入口更推荐直接写 `@import 'weapp-tailwindcss/index.css'`。如果这里继续写 `@import 'tailwindcss'`，则依赖 `rewriteCssImports` 在构建阶段自动改写。

这样在 `tailwindcss@4` 中才能起效果

## icon预览挑选网站

https://icon-sets.iconify.design/

<https://icones.js.org>

## 生成结果

我们以 `i-mdi-home` 这个类的`css` 生成结果为例：

```css
.i-mdi-home{
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  -webkit-mask-image: var(--svg);
  mask-image: var(--svg);
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-size: 100% 100%;
  mask-size: 100% 100%;
  --svg: url("data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 24 24%27 width=%2724%27 height=%2724%27%3E%3Cpath fill=%27black%27 d=%27M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z%27/%3E%3C/svg%3E");
}
```

是的，它是通过 `css var` 的方式，把 `svg` 给内联了（`inline`）了进来，然后通过 `mask-image` 来把图形给显示出来的。 显然，这用多了 `icon` 之后会造成生成的 `css` 体积大的问题。

对此还有 `mask-image` 和 `css var` 在部分机器上不兼容的问题。

对此有解决方案吗？显然是有的，比如我们可以把它做成一个 `webfont`，更改每一个 `icon component class`，把里面换成字体，达到类似 `iconfont` 的效果，最后再生成一份 `ttf/woff` 等文件上传到自己的 `cdn`去，然后这里再引用即可。

这样小程序体积又小，兼容性也好，就是多了些网络请求罢了,我们自己取舍吧。

---

## 💨跨多端开发CSS兼容


## 何时开启插件

本插件主要作用于小程序环境，让开发者可以在小程序环境下可以使用 `tailwindcss` 的特性

然而在 `h5` 和 `app` 中，它们本来就是 `tailwindcss` 支持的环境，所以是没有必要开启本插件的。

所以你可以这样传入 `disabled` 选项。

### uni-app 示例

比如 `uni-app`:

```js title="vite.config.[jt]s"
const isH5 = process.env.UNI_PLATFORM === "h5";
// uni-app v2
// const isApp = process.env.UNI_PLATFORM === "app-plus";
// uni-app v3
const isApp = process.env.UNI_PLATFORM === "app";
// 只在小程序平台开启 weapp-tailwindcss 插件
// highlight-next-line
const WeappTailwindcssDisabled = isH5 || isApp;

const vitePlugins = [
  uni(),
  uvwt({
    // highlight-next-line
    disabled: WeappTailwindcssDisabled
  })
];
```

### Taro 示例

```js title="config/index.ts"
const isH5 = process.env.TARO_ENV === "h5";
const isApp = process.env.TARO_ENV === "rn";
// highlight-next-line
const WeappTailwindcssDisabled = isH5 || isApp;

webpackChain(chain) {
  chain.merge({
    plugin: {
      install: {
        plugin: UnifiedWebpackPluginV5,
        args: [
          {
            // highlight-next-line
            disabled: WeappTailwindcssDisabled,
            rem2rpx: true
          }
        ]
      }
    }
  });
},
```

其他的框架，请自行在对应的文档中，发掘不同目标平台的环境变量判断方式。

## uni-app 打包到 h5 svg icon 偏移问题

这是由于 `tailwindcss` 默认会把 `svg` 的 `display` 设置成 `block` 导致的，所以解决方案很简单

在你的全局样式，引入 `tailwindcss` 的地方下面加一行，进行样式覆盖:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
/*  #ifdef  H5  */
svg {
  display: initial;
}
/*  #endif  */
```

## uni-app 打包安卓 `rgb()` 颜色失效问题

这是由于 `uni-app` 打包成安卓中 `webview` 内核版本较低，无法兼容 `rgb(245 247 255 / var(--tw-bg-opacity))` 这样的 `css` 写法导致的

这时候我们需要把这个写法，转换为兼容写法: `rgba(245, 247, 255, var(--tw-bg-opacity))`，具体解决方案:

### 安装 `postcss-preset-env`

```bash npm2yarn
npm i -D postcss-preset-env
```

### 设置 `postcss.config.js`

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-preset-env': {
      browsers: 'chrome >= 50', // configure a compatible browser version
    },
  },
};
```

这样，所有的 `rgb` 和 `/` 写法就被转化成兼容写法了。

相关issue详见:<https://github.com/tailwindlabs/tailwindcss/issues/7618#issuecomment-1140693288>

## CSS变量计算模式

在 `tailwindcss@4` 下，默认启用 CSS 变量计算模式。`tailwindcss@3` 默认不启用。

此模式下会去预编译所有的 `css` 变量和 `calc` 计算表达式。

比如 `tailwindcss@4` 下原先生成的样式为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

在CSS变量计算模式启动，进行预编译之后，现在的结果为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
 height: calc(var(--spacing) * 2);
}
```

这个模式可以解决很多手机机型 `calc` `rpx` 单位的兼容问题。\
当处于 Tailwind CSS 模式（`tailwindcss@4` 及以上）时，插件会默认把 `--spacing` 注入到 `includeCustomProperties`，因此常见的 `space-x`/`space-y` 等工具类会被稳定计算。

> 可通过给插件，传入 `cssCalc` 配置项 `false` 来手动关闭这个功能

假如这时候你需要去除 CSS 变量的声明，你可以传入

```js
{
  cssCalc: ['--spacing']
}
// 或者更精确的
{
  cssCalc: {
    includeCustomProperties: ['--spacing']
  }
}
```

> 你也可以传入正则表达式

这样生成的结果就是:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
}
```

通过这种方式可以解决手机机型 `calc` `rpx` 单位的兼容问题

详见: https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csscalc

### `includeCustomProperties` 进阶用法

`cssCalc` 提供多种写法来控制需要参与计算的自定义属性。下面结合「执行前 / 执行后」的示例说明差异。

**数组写法**

```ts
cssCalc: ['--spacing', '--gap']
```

- 执行前：

  ```css
  :root {
    --gap: 6rpx;
    --spacing: 8rpx;
  }
  .space-x-2>view+view {
    margin-left: calc(var(--gap) * (1 - var(--tw-space-x-reverse)));
    margin-right: calc(var(--spacing) * var(--tw-space-x-reverse));
  }
  ```

- 执行后：

  ```css
  .space-x-2>view+view {
    margin-left: 6rpx;
    margin-right: 8rpx;
  }
  ```

**对象写法**

```ts
cssCalc: {
  includeCustomProperties: ['--gap'],
  precision: 6,
  preserve: true,
}
```

- 执行前：

  ```css
  :root {
    --gap: 12rpx;
  }
  .btn {
    margin-bottom: calc(var(--gap) * 2);
  }
  ```

- 执行后：

  ```css
  :root {
    --gap: 12rpx;
  }
  .btn {
    margin-bottom: 24rpx;
    margin-bottom: calc(var(--gap) * 2);
  }
  ```

**正则写法**

```ts
cssCalc: [/^--(gap|spacing)$/]
```

- 执行前：

  ```css
  :root {
    --gap: 4rpx;
    --spacing: 10rpx;
  }
  .card + .card {
    margin-top: calc(var(--spacing) * 2);
    margin-left: calc(var(--gap) * 3);
  }
  ```

- 执行后：

  ```css
  .card + .card {
    margin-top: 20rpx;
    margin-top: calc(var(--spacing) * 2);
    margin-left: 12rpx;
    margin-left: calc(var(--gap) * 3);
  }
  ```

**Tailwind 统一变量写法**

```ts
cssCalc: {
  includeCustomProperties: [/^--tw-/],
  preserve: true,
}
```

- 执行前：

  ```css
  :root {
    --tw-space-y-reverse: 0;
    --tw-gradient-from: #38bdf8;
    --tw-gradient-stops: var(--tw-gradient-from), rgba(56,189,248,0);
  }
  .space-y-3>view+view {
    margin-top: calc(var(--spacing) * 3 * (1 - var(--tw-space-y-reverse)));
  }
  .from-sky-400 {
    background-image: linear-gradient(to right, var(--tw-gradient-stops));
  }
  ```

- 执行后：

  ```css
  :root {
    --tw-space-y-reverse: 0;
    --tw-gradient-from: #38bdf8;
    --tw-gradient-stops: var(--tw-gradient-from), rgba(56,189,248,0);
  }
  .space-y-3>view+view {
    margin-top: 24rpx;
    margin-top: calc(var(--spacing) * 3 * (1 - var(--tw-space-y-reverse)));
  }
  .from-sky-400 {
    background-image: linear-gradient(to right, var(--tw-gradient-stops));
  }
  ```

以上示例可以自由组合使用，帮助你根据业务场景精确控制 `calc` 与自定义属性的计算范围。

---

## tailwindcss in weapp 的原理

## 2024-02-20 版本

## 前言

转眼又是一年，感觉是时候再来修订一下 `tailwindcss in weapp 的原理` 这篇文章了, 放心，这次我写作核心就是要让大多数人看懂！

## 什么是 weapp-tailwindcss

如果下一个定义的话，我把 `weapp-tailwindcss` 定义成一个 **转义器**，在我看来它就做了一件事情。那就是把 `tailwindcss` 中，小程序不兼容的写法，转化成小程序兼容的写法，并尽量保持生成的 `CSS` 效果一致罢了。

更加细一点的解释，就是允许开发者像 `tailwindcss` `h5` 环境里那样去写小程序，插件在背后帮助你把 `wxml`,`js`,`wxss` 等等这类产物的小程序兼容转化给做了。

仅仅如此罢了，做了一点小小的努力和贡献。

## 为什么需要 weapp-tailwindcss ？

因为小程序 `wxml`,`wxss` 等等文件/产物，本身是不支持 `Tailwindcss` 里面的一些特殊转义字符的，比如像 `[]`,`!`,`.` 等等。

经过测试后，`wxml` 中 `class` 属性，实际上只支持英文字母，数字，以及 `-` 和 `_` 这 `2` 个特殊字符，不支持的字符会被默认转化成**空格**，所以我们要做的就是把 `Tailwindcss` 选择器的写法，转化成小程序允许的方式。这也是核心包 [`@weapp-core/escape`](https://github.com/sonofmagic/weapp-core) 实现的功能。

插件大体的发展历程和方向，可以看下方以前的 `2023-03-19` 版本，在此不再叙述，接下来我们只来谈谈核心原理。

## 核心原理

插件的核心就是转义，那么具体是怎么做的呢？

实际上就是插件去解析编译后的 `wxml`,`js`,`wxss` 这些产物，并对它们进行改写。

工具方面， `weapp-tailwindcss` 使用 `htmlparser2` 去解析改造 `wxml`，使用 `babel` 去解析改造 `js` 和 `wxs`，使用 `postcss` 去解析改造所有的 `wxss`。

## `wxml`

### 为什么是 `htmlparser2`

其实，`weapp-tailwindcss` 一开始使用的是 `@vivaxy/wxml`，这是一个 `wxml` 的 `ast` 工具，

但是它已经很久没有更新了，在很多场景，比如遇到内联的 `wxs` 的时候，会直接挂掉，而本身我也没有技术能力，去修复和完善这个 `wxml` 自动机，所以后续放弃了它。后来自己实现了一套基于正则的模板匹配引擎，但是再使用一段时间后，发现 `正则` 同样是有问题的，比如这样一个 `case`:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会与 `<view class="{{2>` 进行提前匹配并返回，这和我们的期望不符合，而且正则复杂了之后，其实匹配效率也是很低的 (具体可以在 [regex101](https://regex101.com/) 进行测试和调试)，所以还是要使用 `ast` 工具才能做到兼顾效率的同时，做精确匹配转化。

所有，我还是要去寻找对应的 `xml/html ast` 工具来解析 `wxml`。在寻找的过程中，找到了符合条件的一些包，其中 `parse5` 对 `html5` 是严格的匹配，不怎么适用于 `wxml`，而 `htmlparser2` 是不严格标签匹配，所以经过测试之后，最后使用 `htmlparser2` 来处理 `wxml`。

### 如何使用 `htmlparser2`

实际上很简单，我们可以在 `webpack` / `vite` / `gulp` 或者自己的构建脚本中，找到对应的生命周期 (`hooks`)，对 `wxml` 产物进行处理。

首先在获取到 `wxml` 产物的内容之后，把它构造成一个 `MagicString` 对象，因为 `magic-string` 这个库，操作字符串十分方便。

对产物内容字符串进行解析后，获取到所有 `class` 属性的内容，进行转义即可。代码示例如下:

```js

const parser = new htmlparser2.Parser({
    onopentag(name, attributes) {
      // code
    },
    onclosetag(tagname) {
      // code
    },
    // ....
});
parser.write(wxmlCode);
parser.end();
```

### 字符串以及变量绑定的处理

不过在获取到 `class` / `hover-class` 这些标签里面的内容之后，需要进行进一步解析和转化。

为什么？因为原生小程序可以使用 `{{expression}}` 表达式来动态绑定 `js` 的值，假设有一段 `wxml` 是这样写的:

```html
<view class="w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}"></view>
```

这时候你就必须在匹配 `class` 属性值的情况下，对字符串进行转义，再对 `{{}}` 里包裹的 `js` 表达式，进行转义，使得结果变成:

```html
<view class="w-_13px_ {{flag?'h-_23px_':'h-_6px_'}} bg-_#123456_ {{customClass}}"></view>
```

那么怎么做呢？也很简单，我们通过 `htmlparser2` 匹配 `class` 属性，可以获取到 `w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}` 这个字符串。

然后对这个字符串进行 `{{}}` 表达式匹配，在 `{{}}` 表达式匹配之外的字符串，直接进行转义。在 `{{}}` 表达式内的代码，使用 `babel` 进行解析，然后获取到所有的 `js` 字符串字面量，进行转义即可。

同时在进行匹配和转义的时候，实际上我们是可以获取到对应字符串 `start` 和 `end` 的下标的，这就为我们使用 `MagicString` 进行替换，提供了良好的基础。

## js / wxs

我们同样要对所有的 `js` 里面的字符串，进行扫描，发现它是 `tailwindcss` 的类名，就需要进行转义。

我们还是以上方的代码片段为例:

```html
<view class="w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}"></view>
```

在 `wxml` 的处理过程中，看似我们已经解决了大部分 `class` 内容的转义的，但是开发者也可能在 `customClass` 绑定的 `js` 字符串中，直接去编写 `tailwindcss` 的类名。比如:

```js
Page({
  data: {
    customClass: "bg-[url('https://xxx.com/xx.webp')] text-[#123456] text-[50px] bg-[#fff]",
  },
})
```

又或者直接在 `wxs` 里面去写类名，那么这时候怎么办呢？获取所有字符串字面量和模板字符串，进行转义即可吗？

显然这是不行的，一个应用程序里面，大部分的字符串字面量都是和 `tailwindcss` 无关的，假如全部转化只会把应用程序弄奔溃。

那么，我们是否有什么方式，去获取到 `tailwindcss` 的上下文，再从里面把它所有的类名提取出来，再和我们应用程序里面的字符串进行匹配，从而做到精确转义呢？可是 `tailwindcss` 只是一个 `postcss` 插件啊，怎么从 `webpack` / `vite` 插件里，把一个 `postcss` 插件里的内容取出来呢？

通过这种方式，我们可以在 `postcss` / `postcss-loader` 执行之后，把 `tailwindcss` 执行时的 1 或者多个上下文给取出来，交给插件进行使用，从而达到所有 `js` 字符串字面量筛选的效果，简单实用 `babel` 实现的代码如下:

```js
let ast: ParseResult<File> = parse(rawSource, {
    sourceType: 'unambiguous'
})
const ms = new MagicString(rawSource)

const ropt: TraverseOptions<Node> = {
  StringLiteral: {
    enter(p) {
      // set 为 tailwindcss 上下文里所有生效的 classnames
      if(set.has(p.node.value)){
        // do escape
        const value = escape(p.node.value)
        ms.update(start, end, value)
      }
    },
  },
}

traverse(ast, ropt)

const code = ms.toString()
```

通过这种方式来精确的把 `js` / `wxs` 里面字符串字面量，给转义成小程序允许的方式。

这里我们使用 `babel` 作为 `js ast` 的工具，因为目前为止它也是最流行的这方面的包，但是出于效率上的考虑，未来将会使用 `swc` 并编写 `swc` 插件的方式，来取代 `babel`。

## wxss

最后就是样式的处理了，在转义完 `wxml`,`js` 和 `wxs` 后，我们需要把 `wxss` 里 `tailwindcss` 生成的样式，转化成与之前的 `wxml`,`js`,`wxs` 中匹配的方式。这样才能做到类名的 11 对应，从而达到我们最终的目的。

那么怎么做呢？这里我们选用的工具，自然是 `postcss`，它是目前用 `js` 编写的最流行的一个 `css ast` 工具，它要比 `css-tree` 生态好很多，也有很多现成的稳定插件可以使用，帮助我们完成针对 `css` 各种各样的处理。

所以最后我们所要完成的工作，就是把 `tailwindcss` 的产物，转化成与 `wxml`,`js` 和 `wxs` 匹配，且小程序能够适配的样子了！

怎么做？也很简单，直接使用 `postcss` 扫描 `wxss` 里面所有的 `Rule` 节点，然后获取到里面的选择器，进行转义即可！

### postcss 对象简单介绍

什么是 `Rule` 节点？在 `postcss` 插件中，大致有这 `5` 类对象(其实还有一个 `Document` ):

- `Root`: CSS tree 的根结点，通常可以代表整个 CSS 文件.
- `AtRule`: 以 `@` 开始的 CSS 语句，比如 `@charset "UTF-8"` 或者 `@media (screen) {}`.
- `Rule`: 普通的选择器节点，内部由 CSS 声明填充，比如 `.btn { /*decls*/ }`.
- `Declaration`: key-value 键值对，代表 CSS 声明，比如 `color: black`;
- `Comment`: CSS 注释.

详见 [writing-a-postcss-plugin](https://postcss.org/docs/writing-a-postcss-plugin#step-find-nodes)

通过这些对象，`postcss` 完成了对 `CSS` 的抽象，从而让我们可以通过操作这些对象来对 `CSS` 进行增删改查。

### Tailwindcss 简单原理和运行表现

在转化所有的 `Rule` 节点之前，我们先分析一下 `Tailwindcss` 的原理，它也是一个 `postcss` 插件，它通过提取 `content` 配置里面的 `glob` 表达式 or `vfile` 对象，从里面提取到符合它规则的字符串，然后生成大量的 `AtRule` / `Rule` 对象保存起来。

然后再扫描到我们注册 `Tailwindcss` 的地方:

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

把这些对象进行展开，替换掉原先的 `@tailwind xxx;`，从而达到了写什么， `CSS` 就自动生成什么的效果。

其中你可以把 `base` / `components` / `utilities` 理解成一个个 `layer` 标志位，不同的 `AtRule` / `Rule` 对象集合，会在它对应的 `layer` 出展开。比如 `base` 负责所有的 `css vars` 和 `preflight css` 注入，`utilities` 负责所有原子工具类的生成。

同时它们再通过 `@layer` 来控制它们的优先级，从而做到它们之间的 `CSS` 不会产生优先级相互覆盖冲突的问题。

> `@layer` 实际上是原生 `CSS` 的一个实验性功能，用来声明一个 级联层,从而让开发者更容易的控制自己 CSS 代码的优先级罢了。这里我们能使用 `@layer` 是因为这个功能被 `tailwindcss` 用它自己的方式实现了，使得我们可以在 `CSS` 里预先使用 `@layer` 罢了，最终产物里面是没有 `@layer` 的。相关文档详见 [MDN @layer](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@layer)

### 开始转化

首先我们先简单声明一个 `postcss` 插件:

```ts

const creator: PluginCreator<Options> = () => {
  return {
    postcssPlugin,
    Rule(rule) {
      ruleTransformSync(rule, options)
    },
  }
}

creator.postcss = true
```

这里我们把针对 `Rule` 的转化，封装进 `ruleTransformSync` 这个方法里:

这里我们需要用到 `postcss-selector-parser` 来对 `Rule` 中的选择器，做更加细致的转化。

因为 `postcss` 中的 `Rule` 对象的选择器千变万化，可以非常的简单，也可以非常的复杂，你单独把它当作字符串来处理，很容易出现问题。

所以我们需要 `postcss-selector-parser` 来解析 `Rule#selector` 然后进行修改再转化回字符串。

例如:

```ts

export const ruleTransformSync = (rule: Rule, options: IStyleHandlerOptions) => {
  const transformer = selectorParser((selectors) => {
    selectors.walk((selector) => {
      // do something with the selector
    })
  })

  return transformer.transformSync(rule, {
    lossless: false,
    updateSelector: true
  })
}
```

我们通过对 `selectors` 的 `walk`，再方法里面去筛选和修改节点，从而达到我们替换和转义 `Rule#selector` 的效果。

这样就可以去转义所有的 `Tailwindcss` 生成的所有节点了！

## 大功告成

最终在这 3 大部分完成之后，`weapp-tailwindcss` 的核心功能就完成了！

---

## 2023-03-19 版本

(2023-03-19) 版本，现在看了一下，已经比较老了，有空再改进改进。

## 前言

笔者对 `tailwindcss` 这一类库的理解还算比较深刻。之前就已经撰写并发布过相关的许多包，比如像 [`tailwindcss-miniprogram-preset`](https://github.com/sonofmagic/tailwindcss-miniprogram-preset), [`weapp-tailwindcss-webpack-plugin`][weapp-link] [等等大堆的包](https://github.com/sonofmagic?tab=repositories&q=tailwindcss&type=&language=&sort=)。

最近我发布了 [`weapp-tailwindcss-webpack-plugin`][weapp-link] 的 `2.0.0`版本，增加了一些核心特性。想着现在也是时候，回顾总结一下这个插件的原理和历程了。回首`npm`版本发布历史，看到当年发布的第一个正式版，还是在 `2022/2/3` 号，到现在也已经过去了`1`年多的时间了，想想岁月真是如白驹过隙，等着等着我们就老了。

## 这个插件是做什么的？

简单概括一下，就是把 `tailwindcss` 相关的特性，带入进小程序开发中。

为什么需要它呢？核心原因就是，小程序这个平台不像`h5`那么自由，有很多各式各样的束缚与非标准化的 `API`。我们以微信小程序为例：

同`css`相比，`wxss`有着更少的选择器支持，同`wxml`相比，`wxml`有着更少的字符集支持，`js` 和 `wxs` 的运行也是分离的(`wxs`语法像是一个低版本`js`)。

更不用说那些该有的全局对象一个都没有了，比如 `Blob`,`File`,`FormData`, `WebSocket`,`fetch`,`XmlHttpRequest`等等了，这导致许多浏览器包，安装下来无法运行。

> 举个例子，最近我在做服务端 graphql 改造，市面上主流的 `graphql client` 直接安装运行会立即报错，因为缺少全局对象，为了兼容它们，于是就写了 [`weapp-websocket`](https://www.npmjs.com/package/weapp-websocket) 和 [`weapp-fetch`](https://www.npmjs.com/package/weapp-graphql-request) 分别来实现 `subscriptions` 和 `query/mutation`。目前在项目里使用，运转良好。

总的来说，由于缺少许多特定的对象和语法上的限制，一些在 `h5` 上通用的流行库，很有可能在小程序里跑不起来。`tailwindcss` 便是其中之一，而这个插件就能帮助你在小程序里使用它。

## 原理篇

### utility-first CSS framework

其实吧，市面上的 `tailwindcss`/`windicss`/`unocss` 做的是一回事情。如果用比喻来形容，那么它们就是个带着滤网的字符串漏斗。它们对开发者编写的代码文件内容进行读取，并分割成海量的字符串放入漏斗中，然后经过滤网的过滤，符合条件的就去生成原子类，其余的"残渣"则忽略。

其中 `tailwindcss` 大多作为 `postcss plugin` 来使用的，它源码里自己实现了一个文件读取机制(也就是 `tailwind.config.js` 中的 `content` 配置项 )，来对我们编写的代码进行提取。

而 `windicss`/`unocss` 则是依赖 `webpack/rollup/vite` 这类的 `bundler`，在打包的过程中获取到 `Source / Asset / Chunk` 这类的对象，从而提取字符串的。虽然目前 `windicss`/`unocss` 都有对应的 `postcss plugin` 的实现，但是它们大多都是作为实验性质的，并不能很好的复刻它们打包插件的体验。

是什么造成了它们的不同呢？

这点其实就要说到 `unocss/windicss` 它们的优点了。目前 `tailwindcss postcss plugin` 实际上只有**读**的能力，它来读取我们写的代码，生成原子类。而 `windicss`/`unocss` 它们大多作为一个 `webpack/vite/rollup plugin` 来使用的，所以它们不但拥有读的能力，还拥有**修改**的能力。所以它们能写出这样的代码:

```html
<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>

```

实际上就是在打包的插件内，展开覆写罢了，本质上还是个语法糖。

另外目前你选择这种原子类框架的时候，要不选择 `tailwindcss` 要不就 `unocss`，目前看起来 `windicss` 已经死了。

### 小程序兼容

上面说了这么多，接下来来聊聊它们对小程序的兼容，事实上，市面这么多转义的插件，预设啥的，都是一回事。

思路大多就是把这些原子类`css`框架，生成的 `class` 通过重命名，转义，再覆写的方式，去兼容小程序环境。

说的具体一些，就是对打包后的产物进行修改，把其中的 `wxml` 里开发者撰写的 `className` 进行转义，把 `js` 里写的要应用到 `dom` 节点上的 `className` 也进行转义，同时还要对 `wxss` 里生成的 `css` 选择器进行转义。

而这些核心中的核心，便是转义后类名和选择器，一定要相互匹配！！不然生成的结果就是完全错误的。

## 笔者的实现

前面说了这么多，接下来来讲讲我自己的实现。

实际上我一开始的实现也很简单，在第一版本初期，我选择写了这样一个 `webpack plugin`：

1. 它内部用 `wxml ast` 来解析所有的 `wxml`模板,以此来获取所有的 `className` 进行解析和替换
2. 使用 `postcss` 来解析所有的 `wxss`，以此对所有的`css`选择器进行修改
3. 使用 `babel` 来解析所有的 `js`/`jsx`，以此来动态修改 `jsx?` 里所以满足条件的字面量 (`StringLiteral`)。

然而理想很丰满，现实很骨感，在实现的过程中，困难一个一个浮现出来了：

### js里的字面量转义很容易误伤

一开始想着直接匹配并且替换掉符合要求的 `js` 的字面量，于是便兴致勃勃从 `tailwindcss` 源码里，拷贝来了解析提取器的正则，并在打包后进行匹配和替换。

然而这个方案失败了，原因是`tailwindcss`这个正则匹配有可能会把 `webpack` 它默认注入的一些`js code`的一些字面量，也给匹配进来，从而造成大面积误伤。这种误伤会导致 `js` 加载的失败，应用直接就挂了。所以暂时把 `js`字面量动态修改给去除掉了。同时导出了一个手动标记替换位置的方法：

```js

const cardsColor = reactive([
  replaceJs('bg-[#4268EA] shadow-indigo-100'),
  replaceJs('bg-[#123456] shadow-blue-100')
])
```

这样虽然解决了误伤的问题，但是带来了一些代码的入侵性，导致了开发体验不佳。不过这个问题在 `2.0.0` 解决了，请继续往下看。

### 多框架兼容

> 源码 `framework` 部分

正如你看到的，我的这个 `plugin` 是兼容市面上，几乎所有还活着的主流开发框架的。在开始设计兼容方案的过程中，我发现这些框架编译成小程序的产物各有不同，一类是以 `uni-app`/`mpx`/`native(原生)`为例，它们就是按部就班的把类 `vue` 模板的写法，转义成小程序模板写法。另外一类是以 `taro`，`rax`，`remax` 为代表的 `jsx` 写法，这种写法的产物，最大的特点就是页面与组件的 `wxml` 里往往都是这样的结构：

```html
<import src="../../base.wxml"/>
<template is="taro_tmpl" data="{{root:root}}" />
```

而 `base.wxml` 文件内则是大量的条件渲染语句，然后在 `js` 里生成一个对象传入其中，就把整个页面和逻辑渲染出来了。这个方案显然会比模板方案要灵活许多。个人总结，一种偏静态编译，一种偏动态。

所以开始写的时候插件也分成了 `2` 个版本，一个是 `TemplatePlugin` 专门用来处理偏静态的这种框架，一个是 `JsxPlugin` 负责动态的方案。这 `2` 种插件的侧重点不同，一个主要替换模板代码，一个则主要转义 `jsx`，就开发难度来说 `jsx` 插件要难上许多。

#### 模板插件

> 源码 `base/BaseTemplatePlugin` 和 `wxml` 部分

模板那个插件，要做的是解析所有的 `dom` 的 `class` 属性，但是这个属性里很有可能会存在 `js`表达式(`{{}}`包裹的部分)。

如果是不带表达式的，可以直接转义覆写，带表达式的会稍微复杂一点，我需要去预估开发者所使用的语法，比如开发者经常会使用一些数组绑定的语法，或者多元条件运算符，例如 `x?y:z?a:b` 来撰写类名。这就代表着我们需要像解析 `js` 那样去解析 `{{}}` 内部包着的表达式，再通过语法的检测去进行替换。

比如 `x?y:z?a:b` 派生的 `{{ flag ? 'bg-[#123456]' : otherFlag ? 'text-[50px]' : 'text-[#654321]' }}` 我们就需要匹配 `3` 个字面量进行转义。

#### jsx插件

> 源码 `base/BaseJsxPlugin` 和 `jsx` 部分

这个插件的开发难度更高，因为我发现就单单 `taro` 一个框架，它就支持 `react`/ `preact`/ `vue2` / `vue3` 这些框架，要命的是，`react`/`vue2`/`vue3` 它们构建出来的产物，有很大的不同。

> 这点你可以通过我 `src/jsx` 目录下的源码，和相应的`jest`单元测试快照，查看它们的差别。

所以我在配置项里，除了原先的 `appType`(框架) 之外又加了一个 `framework` 专门提供给 `taro`，通过传入 `react/vue2/vue3` 让它们走各自不同的 `jsx?` 替换策略。

当然这样远远没有解决问题，毕竟原先插件是在 `processAssets` 这个`hook`去执行的核心逻辑，相比较来说还是偏晚的，还可能有误伤的问题存在。为此我做了一些努力：

1. 在替换字面量时，只匹配 `react/vue2/vue3`的`return`模板部分代码，放弃函数作用域内字面量的匹配和替换。
2. 为了让这个转义替换的范围足够的精确，就必须要尽可能的提前执行。于是基于这个思路，我想到了在插件里，动态去插入一个自己的 `webpack-loader`:`jsx-rename-loader` (见源码 `src/loader` )

这个 `loader` 会被动态的插入 `jsx?` 文件的加载读取序列中，并确保它在队列的最先执行，即 `babel-loader` 或 `ts-loader` 之前。这样在这个`loader`内部执行转义的时候，得到的原始内容就非常贴近用户自己编写的代码了。

#### webpack4/5 和 vite 的兼容

> 源码 `base` -> `v4/v5` 部分

这一块也是由于各个框架，使用的 `webpack` / `postcss` 版本不同导致的。

不过要达成这个目标还是比较简单的，看看`webpack`文档就可以了，而 `rollup/vite` 这种，它们本身的 `API` 就要比 `webpack` 简单，实现起来也非常简单。

具体举一些例子便是:

```js
// webpack5 动态插入 loader

NormalModule.getCompilationHooks(compilation).loader.(pluginName, (loaderContext, module) => {})
// webpack4
compilation.hooks.normalModuleLoader.tap(pluginName, (loaderContext, module) => {})

// webpack5
compilation.hooks.processAssets
// webpack4
compilation.hooks.optimizeChunkAssets

// webpack5
const Compilation = compiler.webpack.Compilation
const { ConcatSource } = compiler.webpack.sources
// webpack4

// 还有 `loader-utils` 的版本问题

// 还有 Compilation 封闭后 assets 对象不可修改问题等等等等
```

这种问题只要愿意多调试，都能解决。

### css 选择器替换

> 源码 `postcss` 部分

这部分是 `postcss` 的主场，我们知道 `postcss` 本质上就是一个 `css ast` 工具。有了 `ast` 才有了各种各样的转化插件来生成 `css`。

现在我们使用它的核心目标为：找到所有 `tailwindcss` 的生成块，对选择器进行转义。

我们先来解决第一个问题: 怎么找？

#### 找到tailwindcss节点

> 源码 `postcss/mp` 部分

各个框架，它们公共样式文件的路径不同的。比如 `uni-app` 的路径就是 `common/main.wxss`，`taro` 则为 `app.wxss` ，而某些框架更加的奇葩，`common/miniprogram-app.wxss` 等等，这简直就是简直了。

所以我们可以通过用户传入的 `appType` 这个框架类型，以此来精确定位公共样式的位置。不过这个方案后续还经过了许多的优化，核心便是利用 `postcss` 解析，对 `tailwindcss` 所在的文件位置，进行猜测。

这个猜测的方案是由于 `tailwindcss` 的特性实现的。因为 `tailwindcss` 它在生成原子类之前，它会先去注入大量的 `css` 变量，以此来控制所有的原子类的呈现。

所以我们会看到这样一个 `css` 节点

```css
*,:after,:before{
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  /* ..... */
}
```

那么我们就可以认为，找到它，这个文件就是公共样式的所在之处了。不过在寻址时要注意选择器条件和 `-tw-` 变量条件，以此做到精确匹配。

#### 转义原子类选择器

> 源码 `postcss/selectorParser` 和 `shared` 部分

第一个问题解决了，第二个问题接踵而至，怎么换？

直接对所有的选择器进行转义可行吗？显然是不可行的，这只会导致 `css` 的大面积误伤。

我们知道一个`css`选择器，可能很简单也可以很复杂，它可以包含相邻兄弟选择器，子选择器，后代选择器，通用兄弟选择器，伪类选择器，伪元素选择器，还能使用 `,` 来添加选择器。我们必须要对选择器进一步解析，从而做到精确匹配和转义。

这时候就需要 `postcss-selector-parser` 出场了。

我们在使用 `postcss` 进行 `root.walk` 之后，再把符合条件的 `css` 节点进行 `selectors.walk`，从而达成了选择器局部精确转义的效果。

另外由于 `tailwindcss` 默认的 `preflight` 是针对 `h5` 的，所以我们也需要注入自己的小程序 `preflight`，还有一点值得注意就是， `js/wxml` 的转义方法和 `wxss` 的转义方法是不同的，因为 `css` 中，往往会多加一个 `\` 字符。

### 模板解析的重新实现

> 源码 `reg` 和 `wxml/utils` 部分

原先用的 `wxml ast` 是第三方的，已经彻底没人维护了，一直出 `bug`(比如`wxml`内联`wxs`)，于是自己基于正则写了一个模板属性提取器。

这是由于日益增长的需求导致的，原先可能想着模板里，只要支持 `class`/ `hover-class` 这类的属性转义就够了。但是后续发现，用户在定义和使用组件的时候，也会经常把 `className` 作为属性传入进组件，这时候就需要我们自定义生成正则，来对满足条件的属性进行转义了。比如:

```html
<my-com class="bg-[#123456]" hover-class="bg-[#654321]" custom-class="text-[#ff00ff]" happy-attr="text-[green]" sad-attr="text-[blue]"></my-com>
```

默认只匹配转义 `2` 个，怎么行呢？所以开放了 `customAttributesEntities` 配置项，这个配置项会和原先 `class`/ `hover-class` 相关的属性一起进行匹配，从而转化上述例子中所有的 `Arbitrary values`。

### 动态源码补丁

> 源码 `tailwindcss` 部分

很多时候，出于 `tailwindcss` 自身的限制，和技术国情等等原因。我们的 `pr` 往往不会被他们接受，这时候我们就需要自己去修改他们的源码，从而封装一个符合中国国情的 `tailwindcss`。这种可以通过 `fork` 一个新的版本进行发布来做到，也可以通过给源码打补丁做到。

> 注意点：给源码打补丁，这个操作一定要是幂等的，不然重复执行可能会破坏源码的结构

#### 支持自定义长度单位(rpx)

> 源码 `tailwindcss/supportCustomUnit` 部分

自从 `tailwindcss 3.2.x` 开始，由于加入了单位分类校验 [issue#110](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110) 导致原先一些直接在类名里写 `rpx` 的原子类，被错误识别然后被转化成了颜色。

什么意思呢？

比如现在有三个原子类，`text-[#123]`，`text-[30rpx]`，`text-[30px]`，在 `3.2.x` 之前，前一个是字体颜色，后面两个是字体的大小。在这个版本之后，前 **2** 个是颜色，只有最后一个是字体大小了！

这是因为 `tailwindcss` 会对 `mdn` 上合法长度单位进行校验，在合法长度单位列表内，则认为是字体大小，反之则为字体颜色。而 `rpx` 这个单位是微信的独创，不是一个标准的 `css` 单位，自然就在合法长度单位这个集合之外了。

那么如何进行修复支持呢？通过阅读 `tailwindcss` 的源码，会发现它校验单位的方法在 `utils/dataType.js` 这个文件里。

再通过 `babel` 三件套: `parse`，`traverse`,`generate` 可以精确锁定暴露的合法变量列表位置，然后把 `rpx` 这个单位 `push` 进 `ast node.elements`之后，重新生成覆写即可。

## 2.0 增加了什么？

这个版本新增了 `UnifiedWebpackPluginV5`
和 `UnifiedViteWeappTailwindcssPlugin` 这种以 `Unified` 开头的插件。

它们能够自动识别并精确处理所有 `tailwindcss` 的工具类，这意味着它可以同时处理 `wxss`,`wxml` 和 `js` 里静态和动态的 `class`(v1版本只有处理`wxss`,`wxml`静态`class`的能力)。所以你再也不需要在 `js` 里引入并调用 `replaceJs`方法了！由于 `2.x` 插件有精准转化 `js`/`jsx` 的能力，误伤问题得到了有效的解决，也大大提升了 `taro` 这种动态模板框架的开发体验。

欢迎体验，`star`/`fork`。

## 尾言

正如马克·吐温的名言： `To a man with a hammer, everything looks like a nail`。

笔者的方案肯定也会有许多的局限性，本篇文章也不可避免的会出现许多的勘误。

欢迎大佬们指出，也欢迎大家的建议和指点 ^\_^

作者: [ice breaker](https://github.com/sonofmagic)

[weapp-link]: https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin

---

## Related projects


### CLI 工具

[weapp-ide-cli](https://github.com/sonofmagic/utils/tree/main/packages/weapp-ide-cli): 一个微信开发者工具命令行，快速方便的直接启动 ide 进行登录，开发，预览，上传代码等等功能。

### 模板 template

> 目前模板大多还是 `1.x` 的版本，后续我会对模板进行一系列的升级

#### 如何选择？

假如你仅仅是开发一个`小程序` + `h5` 的组合，那么使用 `vscode` 模板就足够了

假如你的项目构建的重点平台是 `app` 那么还是推荐使用 `hbuilderx` 模板，因为 `hbuilderx` 自带了一套 `app` 构建和调试的工具链，可以更好的支持你的开发。

#### 使用`uni-app cli`进行构建 `vscode`开发

[uni-app-vite-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template)

[uni-app-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-vscode-template)

[uni-app-vue2-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-vscode-template)

#### 使用`hbuilderx` 进行构建和开发

[uni-app-vue2-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-hbuilder-template)

[uni-app-vue3-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template)

### tailwindcss plugin

[weapp-tailwindcss-children](https://github.com/sonofmagic/weapp-tailwindcss-children)

### tailwindcss preset

[tailwindcss-miniprogram-preset](https://github.com/sonofmagic/tailwindcss-miniprogram-preset)

---

## 2.x 版本新特性


这个版本新增了 `UnifiedWebpackPluginV5`
和 `UnifiedViteWeappTailwindcssPlugin` 这种 `Unified` 开头的插件。

它们能够自动识别并精确处理所有 `tailwindcss` 的工具类。这意味着它可以同时处理所有文件中的静态或动态的 `class`。

相比`v1`版本只有处理`wxss`,`wxml`静态`class`的能力，使用`v2`版本新的插件，你再也不需要在 `js` 里引入并调用标记方法 `replaceJs`了！`2.x` 插件有精准转化 `js`/`jsx` 的能力，大大提升了 `taro` 这种动态模板框架的开发体验。

## 新插件介绍

`UnifiedWebpackPluginV5` 是一个核心插件，所有使用 `webpack` 进行打包的框架都可以使用它，只需要传入 `appType` 配置项: `uni-app`/`taro`/`rax`/`remax`/`mpx` 等等，如果不传的话，插件会去猜测公共的样式文件位置，并进行转化(有可能不准确)。

目前，这个方案只支持 `tailwindcss v3.2.2` 以上版本和 `webpack5`。同时这个方案依赖 `monkey patch`，所以你应该把

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

加入你的 `package.json`。当然在安装或者更新 `tailwindcss` 后，手动执行 `npx weapp-tw patch` 效果也是一样的，看到 `patch .... successfully` 表示成功。

`UnifiedViteWeappTailwindcssPlugin` 为 `vite` 专用插件，配置项和使用方式也是和上面一致的。

---

## 优秀案例展示

<!-- ⚠️ 该文件由 scripts/update-showcase.ts 自动生成。请运行 `pnpm showcase:update` 以刷新数据。 -->

# 优秀案例展示

以下内容来自 [谁在使用 weapp-tailwindcss ？](https://github.com/sonofmagic/weapp-tailwindcss/issues/270)，列表顺序按照提交时间排序。

> 最近同步：2025年12月31日 16:58

### 区白白

**提交者**：[@shebaoting](https://github.com/shebaoting) · 2024年1月16日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-1893805052)  
区白白是一个针对小区业主的小程序，它将不同的小区变成一个个的线上社区。业主可以在这个线上社区里参与小区事务，享受区白白的其他服务。

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 6 张图片</summary>
  
    
      
      
      
      
      
      
    
  
</details>

### 紫薇告诉你

**提交者**：[@iguojincom](https://github.com/iguojincom) · 2024年4月12日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2050936255)  
ChatGPT+通义千问+360智脑驱动的MBTI测试小程序,有了AI加持,我可以随时更新题库,增加对各种职业的支持,目前来看,AI出题质量还是比较高的,使用tailwindcss+uniapp开发,后端使用php8.2运行webman框架,内置异步的http客户端,还不错

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 3 张图片</summary>
  
    
      
      
      
    
  
</details>

### 今修小程序

**提交者**：[@imaxing](https://github.com/imaxing) · 2024年4月14日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2054102226)  
南通本土手机维修业务小程序

公司/组织/个人：个人

  

### 聚贞顺

**提交者**：[@zheng1716148634](https://github.com/zheng1716148634) · 2024年7月11日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2221971807)  
专业买卖二手自行车平台

公司/组织/个人：公司

  

### 安心校友圈

**提交者**：[@hzbnb](https://github.com/hzbnb) · 2024年9月18日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2358280769)  
大学生内部社交圈子

公司/组织/个人：公司

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 6 张图片</summary>
  
    
      
      
      
      
      
      
    
  
</details>

### 一键呼援

**提交者**：[@daguanren21](https://github.com/daguanren21) · 2024年12月5日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2520218809)  
一键呼援 应用于企业级方案

公司/组织/个人：公司

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 1 张图片</summary>
  
    
      
    
  
</details>

### 杭州数据交易所

**提交者**：[@HyaCiovo](https://github.com/HyaCiovo) · 2025年3月27日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2756185630)  
公司官方微信小程序

公司/组织/个人：公司

  

### 俞行日记

**提交者**：[@yingyu4451](https://github.com/yingyu4451) · 2025年4月3日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2775396678)  
**GitHub**：https://github\.com/yingyu4451/Hospital\-Traveler

一款记录医院访问记录，并统计数据的移动应用。俞行日记不会联网，全程离线单机使用。

个人：AI食材营养分析助手

介绍：接入deepseek的食材营养分析助手

询问开头输入4451可以突破限制。

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 3 张图片</summary>
  
    
      
      
      
    
  
</details>

### [悦骑行](https://yueqixing.com)

**提交者**：[@yunhouhuang](https://github.com/yunhouhuang) · 2025年7月15日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-3071874776)  
**链接**：[https://yueqixing\.com](https://yueqixing.com)

悦骑行3.0版本重构中使用了 TailwindCSS ，极大提升了效率和规范。

- 公司：Guangzhou Jingji Zhiguang Technology Co., Ltd.

  

### [小而美工具](https://whinc.github.io/ucalc-website/)

**提交者**：[@whinc](https://github.com/whinc) · 2025年11月16日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-3537484222)  
**链接**：[https://whinc\.github\.io/ucalc\-website/](https://whinc.github.io/ucalc-website/)  
**GitHub**：[https://github\.com/whinc/ucalc\-website](https://github.com/whinc/ucalc-website)

用心开发 100 款小而美的大众工具

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 2 张图片</summary>
  
    
      
      
    
  
</details>

### 元气番茄钟

**提交者**：[@puppet-king](https://github.com/puppet-king) · 2025年12月31日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-3701463750)  
简约时尚的番茄工作法的计时工具

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 1 张图片</summary>
  
    
      
    
  
</details>

---

## 成为 weapp-tailwindcss 的赞助商


`weapp-tailwindcss` 是采用 `MIT` 许可的开源项目，使用完全免费。

维护这样一个功能，实际上是非常消耗精力的，而且产生不了什么实际的经济收益。

当然，我个人对于经济收益，还是不怎么在乎的，谁让我喜欢做开源呢？

<!-- 当然废话说了这么多，差点忘了这个页面是用来要钱的。（网络乞丐...） -->

但转念一想，我希望这个项目离开了我之后，还能有生命力，还能找到人维护，

那么它最好能产生一定的经济收益，不然其他人没有人愿意白白贡献代码的。

## 赞助方式

有小额打赏意愿的朋友，你的打赏会被记录在 [sponsors](https://github.com/sonofmagic/sponsors) 仓库中，生成图片挂在我的博客站点。

大额大赏的朋友，可以进行官网广告位的投放，具体的投放的网址，样式由你来定。

当然也可以什么都不给，大家加个微信，交个朋友，也是极好的！

## <!--

但是话又说回来了，我又还是想要一些经济收益（我就是既要又要的伪君子），原因非常简单:

因为钱这个玩意，能够给人自由。

人啊，表面上看寿命大差不差，但生命的质量和长度却大不相同。

像我这个年纪，已经走到了人生的中位，

- 结了婚，是一名丈夫。
- 有了自己的孩子，是一位父亲。
- 每天忙忙碌碌，开会，加班，是一名职场社畜

然而，当我深夜回顾往事的时候，却发现我所铭记的，那些珍藏在心底的记忆点，并不是那些耗费我最多时间的工作:

- 而是那一年，我付了 `800` 元去产房陪产，亲眼看到我的女儿，在下午的 `2点54分` 从产道里出生的惊奇。
- 是那一年，我和爱人骑着`9.9`元周卡的共享单车，听着`《成都》`骑到玉林路小酒馆的门口，穿过拥挤的人群，去隔街买了只烤兔，发现竟然格外好吃的欣喜。(至今依然是我吃过的最好吃的烤兔)
- 也是那一年，我大学时光里熬夜打 `DNF` 搬砖卖金币换钱，收获的纯粹的快乐。(那时候交易平台汇率好像是 `20多万金币换1元`)

所以想想啊，人生如白驹过隙，我们还能够年轻多少年呢？

再过几年，或者我们就说 **现在**

我们还能像以前那样，有说走就走的勇气和身体吗？

> “人生代代无穷已，江月年年望相似。”

所以啊，越是意识到时间的珍贵，越让我明白努力的意义：

努力赚钱，并不是为了单纯的物质享受，而是为了能够用金钱，去换回属于自己的时间，用来做那些真正值得铭记的事情：

- 我想要陪伴我的女儿成长，陪她走过从懵懂到优秀的每一步；
- 我想要和我的伴侣一起创造更多值得回忆的时刻，让未来的我不留遗憾；
- 我想要留更多的时间给自己，重新感受那些被忙碌淹没的生命的美好。

钱能够买来自由，而自由能让我们更好地掌控自己的生命。

生命的意义，不在于耗尽时间，而在于与爱和希望相拥的每一刻。

> 上面这些话是我随手写的，我自己读了一遍感到有些矫情，如果让你感到不适，可以提个 issue 我把它删掉

--- -->

---

## AI 友好提示与 Demo 运行指南

<TailwindTopicHero topicId="tailwindcss/ai-friendly-and-demos" title="AI 友好提示与 Demo 运行指南" />

## 让模型写得像人

- 原子类天然适合 AI 生成，因为它们是稳定、可组合、低歧义的语料。
- 但“适合生成”不等于“适合交付”。如果没有边界，模型会很快产出看起来能跑、实际上很难维护的代码。
- 所以这页真正讨论的是：怎样给 AI 足够明确的轨道，让输出既快，又还能被人接手。
- React/Vue Demo 在 `apps/react-app`、`apps/vue-app`，可以直接拿来做提示实验、人工复核和类名对照。

## 先抓住 4 个原则

- 给模型上下文，不要只给结果要求。它需要知道你有哪些 token、哪些组件、哪些工具。
- 给模型边界，不要只说“用 Tailwind 写一个组件”。要明确哪些能做，哪些不能做。
- 给模型示范，不要期待它自己猜出你们团队的风格。1 到 2 段高质量示例往往比长篇说明更有效。
- 给模型校验链，不要把“看起来差不多”当作通过。merge、lint、构建和人工抽查都要接上。

如果你准备马上把这套方法用起来，最小可行版本其实很简单：

1. 给模型一段结构化提示。
2. 附一段你认可的组件示例。
3. 明确黑名单和边界。
4. 最后用 `cn`、lint 和构建做一次兜底。

## 提示模板（示例）

```
目标：使用 Tailwind 原子类，遵守设计 tokens（不要写裸色值），用 `cn`/`tailwind-merge` 合并类。
必须：
- 仅使用已存在的色板/间距/圆角 tokens。
- 封装变体时用 `cva` 或 `tailwind-variants`，声明 defaultVariants/compoundVariants。
- 状态类优先 aria/data（示例：`aria-invalid:border-destructive`）。
- 禁止在运行时拼接未声明的动态类。
输出：React/Vue 代码块 + 关键 class 解释。
```

> 小技巧：给 1 到 2 段你认可的“示范类名”，通常比补充一大段抽象原则更有效；再补一个黑名单，能明显降低跑偏概率。

## 结构化提示（即贴即用）

```
你将为原子化 CSS 专题编写组件，遵守现有 tokens/variants。

上下文：
- 仓库：weapp-tailwindcss，React 在 apps/react-app，Vue 在 apps/vue-app。
- 工具链：Tailwind v4 JIT，`cn` 内置 tailwind-merge，Button/Badge 已用 cva 定义。
- 设计：使用 OKLCH 色板、`--radius`，暗色通过 `.dark` 或 `data-theme` 切换。

必须：
- 仅用已有 tokens（不要写裸色/px），类名可组合但需可读。
- 变体用 `cva`/`tailwind-variants`，声明 defaultVariants + compoundVariants。
- 状态优先 `aria-` / `data-` / `group` / `peer`，最多两层关系类。
- 给出 React + Vue 代码块，附 1-2 行解释，禁止 inline style/随机色值。

禁用：
- 运行时字符串拼接类名、未注册的自定义色值、超过两层的关系类。
- 依赖未在仓库中的第三方 UI 库（shadcn-ui 已内置）。

输出：
- React 代码块（tsx）+ Vue 代码块（vue SFC），包含 class 解释或推荐检查清单。
- 若需要安装/运行命令，给出 `pnpm --filter react-app dev` / `pnpm --filter vue-app dev`。
```

## 示例输出（React/Vue，对应提示）

<Tabs>
  <TabItem value="react" label="React">

```tsx

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})

export function Promo() {
  return (
    
      已启用原子化工作流
      <button className="underline decoration-dotted">查看指南</button>
    
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<script setup lang="ts">

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})
</script>

<template>
  
    已启用原子化工作流
    <button class="underline decoration-dotted">查看指南</button>
  
</template>
```

  </TabItem>
</Tabs>

## 常见错误与防护

- 类冲突：统一通过 `cn` 包装 `tailwind-merge`，避免 `p-2 p-4` 这类冲突类残留；自定义尺寸和色板也要补 merge 规则。
- 断点缺失：明确 mobile-first，必要时补 `sm:`、`md:`、`lg:`，并把“默认按移动端先写”写进提示里。
- 未注册色值：统一从 token 取值，明确禁止 `text-[#123456]` 或任意 `rgb(...)`。
- 动态类膨胀：避免字符串拼类；如果确实需要动态，改成 `cva` / `tv` 的枚举参数。
- 关系类过深：`group` / `peer` 超过两层后可读性会明显下降，最好直接写进提示约束。

## 失败案例长什么样

下面这类输出，通常看起来“像是完成了任务”，但很难进入正式工程：

```tsx title="失败示例：常见的 AI 跑偏写法"
export function Banner({ type, active }: { type: string; active: boolean }) {
  return (
    
      状态提示
    
  )
}
```

这段代码的问题通常包括：

- 随机 hex 色值，脱离 token 体系。
- 任意值过多，缺少复用空间。
- 运行时字符串拼类，构建和审查都不稳定。
- `group` / `peer` 关系乱用，读者很难判断真实意图。

更稳的做法通常是：

- 先给模型 token 和 builder 的上下文。
- 限制动态空间，只允许枚举值。
- 明确禁止随机色值和超过两层的关系类。
- 最后让 `cn`、lint 和构建做兜底。

## React/Vue 运行与查看

- 安装依赖（首次）：`pnpm install`
- 运行 React Demo：`pnpm --filter react-app dev`
- 运行 Vue Demo：`pnpm --filter vue-app dev`
- 构建文档（可选）：`pnpm --filter website build` 或 `pnpm build:docs`（若有别名）
- 截图占位：`<!-- screenshot: tailwindcss-react-demo -->`、`<!-- screenshot: tailwindcss-vue-demo -->`

## Demo 内容速览

- 主题切换：通过 `.dark` 切换 tokens，组件自动继承，观感差异明显。
- 变体封装：Button/Badge/Input 使用 `cva`，可观察 `tailwind-merge` 去重；可在 UI 中切换 variant/size 看类名组合效果。
- 交互：表单验证态（aria-invalid）、数据卡片、清单列表、小型表格/统计。可按提示模板让模型补充新卡片，验证 merge/lint 是否兜底。

如果你只是想快速验证一遍，不需要全看完：

- 先运行一个 Demo。
- 用上面的提示模板让 AI 生成一个小组件。
- 检查有没有裸色、字符串拼类、过深的关系类。
- 最后跑一次构建，确认结果能进工程。

## 关键代码片段

```tsx title="React：variants + merge"

const pill = cva('inline-flex items-center rounded-full text-xs font-medium', {
  variants: {
    tone: { info: 'bg-blue-50 text-blue-900', success: 'bg-emerald-50 text-emerald-900' },
    dense: { true: 'px-2 py-1', false: 'px-3 py-1.5' },
  },
  defaultVariants: { dense: false, tone: 'info' },
})

export function Pill({ className, ...rest }: { className?: string }) {
  return AI-ready
}
```

```html title="Vue：cva + data 状态"
<script setup lang="ts">

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})
</script>

<template>
  
    已启用原子化工作流
    <button class="underline decoration-dotted">查看指南</button>
  
</template>
```

## 校验链建议（让 AI 结果可交付）

- 静态校验：ESLint、Tailwind IntelliSense、`cn` 包装的 `tailwind-merge`，以及对 `content` 目录的规则检查。
- 人工抽查：每个 PR 至少抽查 1 到 2 个组件，确认没有裸色、裸间距和失控的关系类。
- 产物验证：构建后记录 CSS 体积，并检查主色板是否真的来自 tokens。
- 回归基线：对按钮、表单、卡片等高频组件保留 Story 或截图，方便判断 AI 输出是否开始漂移。

###  流程示意

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 55, "rankSpacing": 75 } } }%%
flowchart TB
  Prompt["结构化提示"]
  Gen["生成 React/Vue"]
  Merge["cn(twMerge) 去重"]
  Lint["ESLint + Tailwind 提示"]
  Build["pnpm build / dev"]
  Review["人工 Spot Check"]
  Snapshot["截图 / Story 基线"]
  Deploy["上线 / 分发"]
  Metrics["CSS 体积 / coverage"]

  Prompt --> Gen --> Merge --> Lint --> Build --> Review --> Snapshot --> Deploy
  Build --> Metrics --> Review
```

  
    
    Prompt/Gen：给出结构化提示，产出 React/Vue 代码。
  
  
    
    Merge/Lint：cn(twMerge) 去重 + ESLint/Tailwind 提示兜底。
  
  
    
    Build/Review：构建验证 + 人工 spot check，再做截图基线。
  
  
    
    Metrics：记录 CSS 体积/覆盖率，支撑迭代。

---

## BEM 与 OOCSS 方法论

<TailwindTopicHero topicId="tailwindcss/bem-and-oocss" title="BEM 与 OOCSS 方法论" />

## BEM（Block / Element / Modifier）

- 目标：通过约定命名减少层级选择器，保证组件内聚且易于组合。
- 命名：`block` 描述独立组件，`block__element` 表示内部元素，`block--modifier` 表示单一维度的变体/状态；不要把多维状态堆在同一个 modifier 上。
- 适用：多页面或老项目中需要稳定、可读的类名约束；也常用作 JS/测试的钩子。

### 示例

```html
<article class="card card--featured">
  <header class="card__header">
    标题
    <button class="card__action card__action--primary">查看</button>
  </header>
  说明文案
</article>
```

```css
.card { border: 1px solid #e5e7eb; padding: 16px; border-radius: 12px; background: #fff; }
.card__header { display: flex; align-items: center; gap: 8px; }
.card__title { margin: 0; font-size: 16px; }
.card__action { border: none; background: transparent; color: #6b7280; cursor: pointer; }
.card__action--primary { color: #2563eb; font-weight: 600; }
.card--featured { border-color: #2563eb; box-shadow: 0 12px 32px rgba(37, 99, 235, 0.12); }
```

- 优势：类名自描述、可组合；元素/变体边界清晰，方便拆分文件。
- 常见坑：嵌套层级依然可能增加（`card__header__title` 违背 BEM）；modifier 爆炸时需要回收公共样式或引入 tokens。
- 与 Tailwind：若转向原子化，可保留 block/element 作为数据钩子，把视觉交给 utilities；或在少量需要全局复用的容器上维持 BEM。

## OOCSS（Object-Oriented CSS）

- 目标：把样式拆成「结构对象」与「皮肤对象」，鼓励复用组合，减少耦合。
- 核心原则：结构与皮肤分离（布局 vs. 视觉）、容器与内容解耦（对象独立、可嵌套）、单一职责（一个类只管一个维度）。
- 适用：设计系统或多主题场景，尤其需要跨组件复用相同布局骨架时。

### 示例

```css
/* 结构对象：媒体块骨架 */
.media { display: grid; grid-template-columns: auto 1fr; gap: 12px; align-items: start; }
.media__img { width: 56px; height: 56px; object-fit: cover; border-radius: 12px; }
.media__body { display: grid; gap: 4px; }

/* 皮肤对象：可在不同地方复用 */
.card-skin { padding: 16px; border: 1px solid #e5e7eb; border-radius: 16px; background: #fff; }
.card-skin--muted { background: #f9fafb; color: #4b5563; }
.tag-skin { display: inline-flex; align-items: center; padding: 4px 8px; border-radius: 999px; background: #eef2ff; color: #4338ca; font-size: 12px; }
```

```html
<article class="media card-skin card-skin--muted">
  
  
    Pro
    对象结构 + 皮肤组合得到卡片
  
</article>

  
  
    同一结构对象
    换皮肤即可变成标签、卡片或列表项
  

```

- 优势：抽象出「可实例化」的样式对象，减少重复 CSS；皮肤可在不改结构的前提下切换。
- 局限：类名数量增多；复杂状态可能需要额外的状态类或 JS 参与。
- 与 Tailwind：Tailwind 的 utility/variants 本质也在拆结构与皮肤，只是把对象拆得更细。迁移时可以把常用 OOCSS 对象翻译成原子组合（或 `@apply`），保留组件语义但减轻样式维护。

---

## 原子化 CSS 最佳实践

<TailwindTopicHero topicId="tailwindcss/best-practices" title="原子化 CSS 最佳实践" />

## 先给结论

- 如果你只打算记住这一页的 3 件事，就记下面这 3 条：
- 先建设计体系，再写类名。不要让每个组件自己发明颜色、间距和尺寸。
- 先收敛组件变体，再谈复用。不要把 `className` 拼接当作唯一扩展方式。
- 先验证产物，再相信感觉。包体、扫描范围、动态类都应该有检查手段。

## 为什么很多团队会把 Tailwind 用乱

- 因为它上手太快，容易直接跳过“设计约束”这一步。
- 因为它试验成本低，组件在早期很顺手，但随着状态增多，类名会在业务代码里蔓延。
- 因为很多问题不是马上爆炸，而是等到评审、迁移、换主题、接 AI 时才暴露。

所以这一页不是教你“还能再写哪些类”，而是帮你建立一套不容易失控的使用方式。

## 设计体系与 tokens

- 先把色板、间距、圆角、阴影、字号这些核心值定成 tokens，并映射到 CSS 变量或 `@theme inline`。
- 最好保留一份“设计稿值 -> token 名称”的对照表。它看起来像文档工作，实际上能显著降低新人理解成本。
- 主题切换建议通过 `data-theme` 或 `.dark` 改 token，不要在 class 里直接写颜色值。
- 如果有多品牌需求，优先把“品牌变量”和“暗色变量”拆开管理，不然很容易相互污染。

除了视觉 token，布局也值得抽成一层稳定组合。这样团队记住的是模式，而不是每次从头拼字符串。

### 反例对照：不要让值散落在组件里

```tsx title="不推荐：裸值直接写进业务组件"
export function PromoCard() {
  return (
    <section className="rounded-[18px] bg-[#3b82f6] px-[18px] py-[14px] text-[15px] text-white shadow-[0_8px_30px_rgba(59,130,246,0.22)]">
      限时活动
    </section>
  )
}
```

```tsx title="推荐：先对齐 token，再消费 token"
export function PromoCard() {
  return (
    <section className="rounded-card bg-brand-500 px-4 py-3 text-sm text-white shadow-brand">
      限时活动
    </section>
  )
}
```

前一种写法短期看更快，长期的问题是换主题、统一视觉、做评审时都很难收敛。

```ts
// Stack（竖向间距统一）
const stack = 'flex flex-col gap-4'
// Cluster（行内 wrap 排布，适合标签/按钮组）
const cluster = 'flex flex-wrap items-center gap-2'
// Sidebar（主体 + 侧栏）
const sidebar = 'grid gap-4 lg:grid-cols-[1fr,360px]'
```

## 组件与变体

这部分的核心原则是：把变化集中，把默认值写死。

- 用 `cva`/`tv` 描述 variants/defaultVariants/compoundVariants，示例：

```ts
const card = cva('rounded-2xl border bg-card/80 shadow-sm transition-all', {
  variants: {
    tone: { neutral: 'border-border', brand: 'border-primary/40 shadow-lg', subtle: 'border-muted bg-muted/60' },
    interactive: { true: 'hover:-translate-y-0.5 hover:shadow-md' },
  },
  defaultVariants: { tone: 'neutral', interactive: true },
})
```

常见组合方式：

- `group`/`peer`：适合父子联动或兄弟联动，例如 hover 某一项时带动图标或描述文案变化。
- `aria-*`：适合表单和交互状态，例如 `aria-invalid`、`aria-busy`，能减少很多额外 JS 判断。
- `data-*`：适合主题和业务状态，例如 `data-theme`、`data-state`，语义通常比自造类名更清楚。
- `tv` slots：适合卡片、弹窗、菜单这类多槽组件，可以把 header/body/footer 的类一起收敛。

这里最常见的坏味道是：状态很多，但状态逻辑分散在不同组件里。只要出现这种情况，后续维护成本一定会上升。

### 反例对照：不要在业务组件里反复拼大串 class

```tsx title="不推荐：状态散落在业务组件里"
export function Notice({ tone = 'info', dense = false }) {
  return (
    
      内容
    
  )
}
```

```tsx title="推荐：把变化集中到 builder"
const notice = cva('rounded-xl border text-sm', {
  variants: {
    tone: {
      info: 'border-sky-200 bg-sky-50 text-sky-900',
      danger: 'border-red-200 bg-red-50 text-red-900',
    },
    dense: {
      true: 'px-2 py-1',
      false: 'px-4 py-3',
    },
  },
  defaultVariants: {
    tone: 'info',
    dense: false,
  },
})
```

这里不是为了“必须上工具”，而是为了让状态和默认值集中在一个地方。

### 业务场景范式

- 表单：输入框用 `focus:ring` 加 `aria-invalid`，错误文案统一走 `text-destructive`，按钮禁用态走 `disabled:`，不要回到内联样式。
- 数据表或列表：优先用 `grid`、`gap`、`minmax` 管列宽，选中态和 hover 态统一收敛到 `data-selected` 之类的状态属性。
- 空状态：给它一套固定骨架，例如 `flex flex-col items-center gap-3 text-center text-muted-foreground`，避免每个页面都重新拼。

## 布局与响应式

- 优先先定容器，再定内容。像 `max-w-screen-xl mx-auto px-4 sm:px-6 lg:px-8` 这种基础容器，应该尽早统一。
- `clamp()` 和 container queries 很适合做“更自然的响应式”，尤其是标题字号和面板栅格。
- 尽量减少 flex/grid 的层层嵌套，能用 `gap` 解决的，不要再靠 margin 互推。
- 对大多数内容区布局，栅格通常比一层层 `md:flex-row` 更直观、更容易审阅。

示例（容器查询 + clamp）：

```css
/* 在容器上启用查询 */
.dashboard { @apply container mx-auto px-4; container-type: inline-size; container-name: dash; }

@container dash (min-width: 720px) {
  .stat-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}

.title-fluid { font-size: clamp(1.25rem, 1.8vw, 1.5rem); }
```

> 需要在微前端/组件库/第三方嵌入中避免样式污染？详见「[样式隔离方案与原理](./style-isolation)」。

## 性能与体积

- 先盯 `content`，再谈优化。很多 CSS 膨胀问题，根源其实是扫描范围太宽或者存在字符串拼类。
- 构建后要看体积，不要只看页面“似乎能跑”。最好给关键页面留一个基线，比如首页 CSS 不超过多少 KB。
- 必要的动态类，尽量回退到 `@apply`、`cva` 或受限枚举，而不是让运行时自由拼接任意值。
- Tailwind v4 的 JIT 已经很快，真正拖慢冷启动的往往是 content 失控和插件堆太多。

### 反例对照：避免运行时拼接任意类

```ts title="不推荐：运行时拼接任意类"
const cls = `bg-${color}-${level} px-${size}`
```

```ts title="推荐：把动态空间收敛成枚举"
const badge = cva('inline-flex items-center rounded-full', {
  variants: {
    color: {
      brand: 'bg-brand-500 text-white',
      neutral: 'bg-muted text-foreground',
    },
    size: {
      sm: 'px-2 py-1 text-xs',
      md: 'px-3 py-1.5 text-sm',
    },
  },
})
```

后一种写法不只是更稳，也更容易让构建工具、审查者和 AI 都读懂。

## 代码评审清单（示例）

下面这张清单更适合在评审时直接过一遍，而不是等到出问题再回头补规范。

- 类名是否只使用预设 token？有无裸写色值/字号？
- 是否使用了 `cn`/`tailwind-merge` 处理动态组合？有无同类冲突（`p-4` vs `p-2`）？
- variants 是否集中在组件工厂（`cva`/`tv`），而不是散落在业务组件？默认值是否写死？
- 有无 `group`/`peer`/`aria`/`data-*` 的滥用或缺乏语义？关系链是否超过 2 层？
- content 匹配是否过宽，是否引入了动态类？是否有字符串拼接类名？
- 文档/示例是否同步更新运行命令与截图占位？有没有给出「推荐类名组合」列表？

快速展示（表格版）：

| 维度 | 要求 | 检查方式 |
| --- | --- | --- |
| tokens | 不写裸色/裸间距 | 搜索 `#`/`px`/`rgb(`；查看配置映射 |
| variants | 集中在 `cva`/`tv` | 查 `variants`/`compoundVariants` 是否在单点声明 |
| merge | 动态类统一走 `cn` | 搜索 `clsx`/`classNames` 是否零散存在 |
| 关系类 | `group/peer/aria/data` ≤ 2 层 | 抽查组件 class 字符串长度与层级 |
| content | 精准扫描模板 | 检查 `tailwind.config` 的 content 路径 |
| 产物 | CSS 体积可控 | 构建后查看 CSS 体积/coverage |

## 常见坑与对策

- 类顺序冲突：使用 `tailwind-merge`；在组件入口统一使用 `cn`，不要散落 `clsx`。
- 自定义色未注册：用 tokens 或在 `@theme`/配置中声明；避免 `text-[#123]` 这类零散值，必要时创建 `brand-50/100/...`。
- 断点误用：确认 mobile-first；自测关键断点（sm/md/lg/xl），尤其是 `gap`/`grid` 在小屏的表现。
- preflight 冲突：在可发布组件库或微前端中谨慎启用，可局部关闭。
- 插件过度：typography/forms 很方便，但要检查是否影响宿主样式；可以按需导入或局部关闭。

---

## CSS 的诞生与演化

<TailwindTopicHero topicId="tailwindcss/css-origin-evolution" title="CSS 的诞生与演化" />

## 要点

- 起因：HTML 早期的表现与结构耦合（`<font>`、table 布局），浏览器厂商私有标签泛滥，缺少跨页面的样式复用。
- CSS 让样式与结构分离，浏览器统一解析模型；随后通过模块化迭代（CSS1 → CSS2 → CSS3/Level 3+）。
- 核心演化方向：布局（float → Flexbox → Grid）、响应式（媒体查询 → 容器查询）、可维护性（自定义属性/层级/逻辑选择器）、性能与工具链（预处理、后处理、JIT 原子化）。
- 今天的场景：多 runtime（Web/RSC/小程序/Native），依赖 tokens、原子类和编译期工具保持一致性与性能。

## CSS 诞生的背景

- 1994 年，Håkon Wium Lie 在 CERN 提出「层叠样式表」，与 HTML 分离表现层，降低表现标签膨胀。
- 1996 年发布 CSS1：定义选择器、层叠与继承模型、字体与文本、颜色与背景等基础能力。
- 设计目标：
  - **分离结构与表现**：HTML 只描述语义/结构；样式由 CSS 控制。
  - **层叠与继承**：同一元素接受多来源样式（作者/用户/UA），按优先级与权重合并。
  - **跨页面复用**：外链样式表 `link`，避免每页重复写内联。

## 时间脉络（里程碑）

```mermaid
%%{ init: { "themeVariables": { "fontSize": "16px", "fontFamily": "Inter, 'Helvetica Neue', Arial, sans-serif" }, "flowchart": { "curve": "basis", "nodeSpacing": 28, "rankSpacing": 22 } } }%%
flowchart LR
  A["1996 · CSS1字体/颜色/背景"] --> B["1998 · CSS2媒体类型、定位、@media"]
  B --> C["2009 · CSS2.1 完成修补兼容性"] --> D["2009 · Flexbox 初稿"]
  D --> E["2011 · CSS3 模块化Transforms/Transitions"]
  E --> F["2017 · Grid 正式落地"]
  F --> G["2021 · Cascade Layers / @layer"]
  G --> H["2022 · Container Queries"]
  H --> I["2024 · CSS Nesting 标准化:has() / 色彩 / 媒体新特性"]
```

## 演化主线

- **布局体系**：table → float 清除 → 多栏 → Flexbox（单轴）→ Grid（二维）→ subgrid/容器查询协同，极大减少包装 div 数量。
- **响应式与适配**：`@media` → 自适应单位（vw/vh/rem）→ `@container`（基于容器尺寸）→ View Transitions/新媒体特性（动态范围、首选配色、指针类型）。
- **可维护性**：自定义属性（CSS 变量）支撑 design tokens；`@layer`、`:where()`、`:is()`、`@scope`（提案中）帮助管理优先级；`color-mix`/`lab` 等色彩空间。
- **表现与交互**：Transforms/Transitions/Animations → 滚动驱动动画（Scroll-driven Animations）、`view-transition-name`。
- **工具链/性能**：Sass/Less 等预处理器 → PostCSS 自动补全/压缩 → 原子化 + JIT（Tailwind/Uno）→ 编译期 CSS-in-JS（vanilla-extract/stylex/Linaria）减少运行时。

## 与现代方案的衔接

- **语义化**：从全局命名（BEM）到组件/作用域（CSS Modules、Scoped、CSS-in-JS），再到类名弱语义但组合语义强的原子化；自定义属性承担语义载体。
- **信息密度**：媒体查询/断点复用、Tokens/原子化/recipes（`cva`/`tv`/Panda）提高密度，避免在模板重复写数值。
- **多运行时**：小程序/Native 需提前编译、限制动态样式；RSC/SSR 要求零或极薄运行时注入；统一 token 表成为跨端桥梁。
- **性能**：HTTP/2+ 多路复用、`content-visibility`/`contain` 提升渲染；JIT/摇树裁剪未用样式；`@layer` 让原子库与自定义样式共存而不失控。

## 继续阅读

- [样式方案时间轴](/docs/tailwindcss/history)
- [Utility-first 与 JIT](/docs/tailwindcss/history/utility-first)
- [CSS-in-JS 阶段](/docs/tailwindcss/history/css-in-js)

---

## 各样式方案 Demo 与产物对照

<TailwindTopicHero topicId="tailwindcss/demos" title="各样式方案 Demo 与产物对照" />

## 目标与产物

- 统一用一张「卡片 + 按钮」UI，展示不同样式方案的实现方式。
- 每个方案给出：核心代码片段、运行思路、预期产物（截图占位或构建结果描述）。
- 可以把片段复制到 `apps/react-app` 或 `apps/vue-app` 中对比，或单独放入 `tmp/style-demos/` 做对照。

> 注：产物大小/性能需本地测量；下方给出测量命令。截图占位：`<!-- screenshot: style-demo-{方案名} -->`。

## 测量命令（可选）

- 运行 React Demo（Tailwind/Headless 版本已内置）：`pnpm --filter react-app dev`
- 运行 Vue Demo：`pnpm --filter vue-app dev`
- 若在独立 HTML 中测试：用 `npx serve` 或 VSCode Live Server 打开 HTML，配合浏览器 Coverage 查看实际 CSS 命中。

## Demo 片段

### Raw CSS / BEM

```html
<section class="card card--elevated">
  <header class="card__header">
    Raw CSS / BEM
    小而直接，没有工具链
    全局命名，命中简单，但易被覆盖，需要团队命名纪律。
    <button class="btn btn--primary">查看详情</button>
  </header>
</section>

<style>
  .card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
  .card--elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
  .card__header { display: flex; flex-direction: column; gap: 8px; }
  .eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
  .title { font-size: 18px; margin: 0; }
  .desc { color: #4b5563; font-size: 14px; }
  .btn { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
  .btn--primary:hover { background: #0f172a; }
</style>
```

预期产物：单一 CSS，无拆分；全局命名容易冲突。

### Sass + BEM（含变量）

```scss
$radius: 16px;
$primary: #111827;
$muted: #6b7280;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $radius;
  padding: 16px;
  &--elevated { box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06); }
  &__header { display: flex; flex-direction: column; gap: 8px; }
}

.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: $muted; }
.btn {
  padding: 10px 16px;
  border-radius: $radius - 4px;
  border: 1px solid $primary;
  background: $primary;
  color: #fff;
  &:hover { background: darken($primary, 5%); }
}
```

预期产物：编译成单个 CSS，变量在构建时内联；仍是全局作用域。

### CSS Modules（React）

```tsx title="Card.tsx"

export function Card() {
  return (
    <section className={`${styles.card} ${styles.elevated}`}>
      
        CSS Modules
        作用域隔离
        类名变为哈希，不会与全局冲突。
        <button className={styles.button}>查看详情</button>
      
    </section>
  )
}
```

```css title="Card.module.css"
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
.elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.header { display: flex; flex-direction: column; gap: 8px; }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
```

预期产物：编译后类名哈希化，隔离性好；主题切换需额外 token 管线。

### Vue `<style scoped>`

```html
<template>
  <section class="card">
    Scoped CSS
    作用域隔离（编译时）
    Vue SFC 编译时添加 data-v-xxx，避免全局污染。
    <button class="button">查看详情</button>
  </section>
</template>

<style scoped>
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
</style>
```

预期产物：编译为 data-v-xxx 的 scoped 选择器，避免全局污染；仍需额外管线处理主题/tokens。

### CSS-in-JS（styled-components 示例）

```tsx

const Card = styled.section`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  box-shadow: ${({ elevated }) => (elevated ? '0 10px 30px rgba(0,0,0,0.06)' : 'none')};
`

const Button = styled.button`
  padding: 10px 16px;
  border-radius: 8px;
  border: 1px solid #111827;
  background: #111827;
  color: #fff;
  &:hover { background: #0f172a; }
`

export const Demo = () => (
  <Card elevated>
    CSS-in-JS
    动态样式，组件边界
    <Button>查看详情</Button>
  </Card>
)
```

预期产物：运行时注入样式；要关注 SSR 注水体积与运行时开销。

### Utility-first（Tailwind）

<Tabs>
  <TabItem value="react" label="React">

```tsx
export function TailwindCard() {
  return (
    <section className="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
      Tailwind
      类名即样式
      JIT + tokens；类名一目了然，摇树后产物小。
      <button className="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
        查看详情
      </button>
    </section>
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<template>
  <section class="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
    Tailwind
    类名即样式
    JIT + tokens；类名一目了然，摇树后产物小。
    <button class="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
      查看详情
    </button>
  </section>
</template>
```

  </TabItem>
</Tabs>

预期产物：按需生成的原子类，配合 `content` 精准扫描，产物可控。

### Headless + cva/tailwind-variants（已在 Demo 应用内）

<Tabs>
  <TabItem value="react" label="React">

```tsx

export function HeadlessCard() {
  return (
    <section className="rounded-2xl border bg-card/80 p-4 shadow-sm">
      Headless + cva
      API 与样式解耦
      variants/compoundVariants 集中声明，`tailwind-merge` 兜底。
      
        <button className={cn(buttonVariants({ variant: 'default' }), 'gap-2')}>主按钮</button>
        <button className={buttonVariants({ variant: 'outline', size: 'sm' })}>次按钮</button>
      
    </section>
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<script setup lang="ts">

</script>

<template>
  <section class="rounded-2xl border bg-card/80 p-4 shadow-sm">
    Headless + cva
    API 与样式解耦
    variants/compoundVariants 集中声明，`tailwind-merge` 兜底。
    
      <button :class="cn(buttonVariants({ variant: 'default' }), 'gap-2')">主按钮</button>
      <button :class="buttonVariants({ variant: 'outline', size: 'sm' })">次按钮</button>
    
  </section>
</template>
```

  </TabItem>
</Tabs>

预期产物：原子类 + merge 去重；与设计 token 对齐，可直接在现有 React/Vue Demo 中运行。

## 如何在本仓库验证这些方案

1. Tailwind / Headless：直接运行 `pnpm --filter react-app dev` 或 `pnpm --filter vue-app dev`，对应代码已内置。
2. Raw/Sass/CSS Modules/CSS-in-JS：将上方片段复制到 `tmp/style-demos/`（或现有 app），用 `npx serve tmp/style-demos` 打开，对比样式与产物；Coverage 面板可查看实际命中。
3. 若需要稳定截图，在对应 HTML 旁添加注释占位：`<!-- screenshot: style-demo-css-modules -->`，再用浏览器截图工具生成并放入文档。

---

## 组件库的演进

<TailwindTopicHero topicId="tailwindcss/history/history-component-evolution" title="组件库的演进" />

## 要点

- 组件库从「组件 + 样式捆绑」到「主题化」再到「Headless Primitives」，逐步把 API、样式与 design tokens 解耦。
- Headless + tokens 让原子类/设计体系可落地，需通过 `cva`/`tailwind-variants` 等集中声明 variants，配合 `tailwind-merge` 兜底。
- 迁移策略：先抽离公共 tokens，再为组件提供 class 注入/无样式模式，最后用 Headless 模板替换关键组件。

> 样式方案本身的演化见：[样式方案的演化](/docs/tailwindcss/history)。

##  演进阶段与对比

| 阶段 | 代表 | 特点 | 问题 |
| --- | --- | --- | --- |
| 传统 UI 套件 | Element, AntD | 样式随组件绑定，主题切换成本高 | 自定义成本高，覆盖样式易碎 |
| 设计体系化 | Chakra, MUI | 主题与 tokens，部分可组合 | 仍有样式耦合，深层改造困难 |
| Headless/UI primitives | Headless UI, shadcn/ui, reka-ui, Radix Primitives | API 与样式解耦，留出 design layer | 需要自己的 design system 与类名约束 |

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 32, "rankSpacing": 24 } } }%%
flowchart TB
  C1["2017 · Element / AntD：组件 + 样式捆绑"]
  C2["2019 · Chakra / MUI：主题与组件半解耦"]
  C3["2022 · Headless UI / Radix：API 与样式分离"]
  C4["2023 · shadcn/ui, reka-ui：Headless + tokens + Tailwind"]

  C1 --> C2 --> C3 --> C4
```

  
    
    2017：传统组件库，样式与组件强绑定。
  
  
    
    2019：主题化/设计体系化的组件库。
  
  
    
    2022：Headless Primitives，API 与样式解耦。
  
  
    
    2023：shadcn/ui 等模板化方案，Headless + tokens + Tailwind。
  

## Headless 组合范式的优劣

- 优势：
  - API 与样式拆分，样式完全交给 Tailwind/Uno + tokens；易于多品牌/暗色切换。
  - 与 `cva`/`tailwind-variants` 配合，变体集中声明，降低审阅成本。
  - 对 AI 生成友好：模板固定，类名受 merge/lint 保护。
- 劣势：
  - 需要自建设计系统与 token 表，否则不同页面风格易漂移。
  - 文档/示例建设成本高，需要给出「推荐类名组合」。
  - 对初学者，class 可读性与语义化需要额外培训。

## 迁移与落地建议

- 抽离 tokens：把色板/间距/字号等设计变量收敛到配置文件，组件仅消费 tokens。
- 无样式接口：为现有组件增加 `className`/`classes` 注入或「unstyled」模式，逐步剥离耦合样式。
- 变体集中：用 `cva`/`tailwind-variants` 建立按钮、输入、卡片等核心组件的变体表，配合 `tailwind-merge` 兜底。
- 评审清单：检查是否仍有深度覆盖、是否存在自定义色值泄漏、是否出现无法复用的 ad-hoc class。

---

## CSS-in-JS 阶段

<TailwindTopicHero topicId="tailwindcss/history/history-css-in-js" title="CSS-in-JS 阶段" />

## 要点

- 组件边界天然隔离，props 可驱动样式；动态主题/状态友好。
- 成本：运行时/SSR 注水体积、构建链复杂；类名可读性差。
- 适合需要高度动态样式、主题切换、设计系统与组件强绑定的团队。
- 代表性包：运行时流派（`styled-components`、`Emotion`、`JSS`）、编译期/零运行时流派（`vanilla-extract`、`Linaria`、`Astro/Uno + scoped` 混合方案）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 组件粒度隔离；props 驱动；可在 JS 里复用逻辑/常量 |
| 劣势 | 运行时开销；SSR 注水；类名调试性差；可能影响 HMR 速度 |
| 适用 | 需要复杂动态样式、主题即逻辑的设计系统；部分 SSR/CSR 混合场景 |
| 不适用 | 对首屏体积极敏感、运行时预算极小的多端/小程序场景 |

## 代表性包与用法

- **styled-components（运行时）**：模板字符串 + props；支持 `ThemeProvider` 统一主题。

```tsx title="styled-components 主题"

const theme = { primary: '#111827', radius: '12px' }
const Button = styled.button`
  padding: 10px 16px;
  border-radius: ${({ theme }) => theme.radius};
  background: ${({ theme }) => theme.primary};
`

export function Demo() {
  return (
    <ThemeProvider theme={theme}>
      <Button>Dark Button</Button>
    </ThemeProvider>
  )
}
```

- **Emotion（运行时 + 编译模式）**：`css` prop 与 `@emotion/babel-plugin` 编译模式减少运行时。

```tsx title="Emotion css prop"

const card = css({
  border: '1px solid #e5e7eb',
  borderRadius: 16,
  padding: 16,
})

export const Card = () => <section css={card}>Emotion css prop</section>
```

- **vanilla-extract（零运行时）**：TypeScript API 生成 CSS，运行时仅使用 className。

```ts title="vanilla-extract button.css.ts"

export const color = createVar()
export const button = style({
  vars: { [color]: '#111827' },
  background: color,
  borderRadius: '8px',
  color: '#fff',
})
```

- **Panda CSS（编译期 / 零运行时）**：Chakra 团队推出的 TS-first 原子化方案，`css`/`cva`/`recipes` API 将设计 Token 编译成静态类名。

```tsx title="Panda CSS recipes"

const badge = css({
  borderRadius: 'full',
  fontWeight: 'semibold',
  px: '3',
  py: '1.5',
  bg: 'blue.50',
  color: 'blue.700',
})

const button = cva({
  base: { borderRadius: 'xl', fontWeight: 'semibold', px: '4', py: '3' },
  variants: {
    intent: {
      solid: { bg: 'blue.600', color: 'white', _hover: { bg: 'blue.700' } },
      ghost: { color: 'blue.700', border: '1px solid #bfdbfe', bg: 'transparent' },
    },
  },
})

export function PandaSection() {
  return (
    <section className={css({ display: 'flex', gap: '3', alignItems: 'center' })}>
      token 驱动
      <button className={button({ intent: 'solid' })}>Panda Button</button>
    </section>
  )
}
```

- **styled-jsx（Next.js 内置，编译期作用域 + 轻量运行时注入）**：JSX 内联 `<style jsx>`，Babel 在编译时生成作用域类名，运行时插入局部 style。

```tsx title="styled-jsx 局部作用域"
export default function StyledJsxCard({ title }: { title: string }) {
  return (
    
      {title}
      Next.js 默认支持，SSR 时自动收集样式。
      <style jsx>{`
        .card {
          padding: 16px;
          border-radius: 12px;
          background: #fff;
          box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
        }
        h3 { margin: 0 0 8px; }
      `}</style>
    
  )
}
```

- **stylex（编译期原子化，零运行时）**：Meta 发布的跨 React Web/Native 工具，受限的 StyleX 语法在编译时拆成原子类，运行时只保留 `stylex.props`。

```tsx title="stylex 原子类"

const styles = stylex.create({
  base: {
    backgroundColor: 'var(--blue-600)',
    borderRadius: 12,
    color: '#fff',
    paddingBlock: 10,
    paddingInline: 16,
    transitionDuration: '150ms',
  },
  hoverable: {
    ':hover': { backgroundColor: 'var(--blue-700)' },
  },
})

export function StylexButton({ hoverable = true }) {
  return <button {...stylex.props(styles.base, hoverable && styles.hoverable)}>StyleX</button>
}
```

##  运行时 vs 编译期（示意）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart LR
  A["源码：styled-components / Emotion"] --> B{"运行时注入？"}
  B -->|是| C["客户端生成 style 标签\n首屏注水 + HMR 成本"]
  B -->|否| D["编译期生成 CSS\nvanilla-extract / Linaria 产出静态 CSS"]
  D --> E["仅 className 传递\n运行时开销小"]
```

  
    
    运行时注入：在客户端生成 style，首屏注水 + HMR 有额外成本。
  
  
    
    编译期生成：静态 CSS 提前产出，JS 只保留 className 映射。
  

### 方案对比（运行时/编译期，七选）

| 方案 | 类型 | 写法/入口 | 动态与主题 | 产物/性能 | 适用 | 
| --- | --- | --- | --- | --- | --- |
| styled-components | 运行时 | `styled` 模板字符串 | 强：props + `ThemeProvider` | JS 注入 style，SSR 需注水 | 组件库、主题切换频繁 |
| Emotion | 运行时/编译混合 | `css` prop / `styled` | 强，Babel 插件可提前抽离 | 默认运行时注入，编译模式减少开销 | React/Next 需要灵活度 |
| styled-jsx | 编译期作用域 + 轻量运行时 | `<style jsx>` 内联 CSS | 中：支持插值但鼓励静态 | 按组件生成作用域 class + style 标签 | Next.js 局部隔离样式 |
| Panda CSS | 编译期 / 零运行时 | `css`/`cva`/`recipes` TS API | 中：受 Token/受限表达式约束 | 产出原子 CSS + class 映射 | 设计 Token 驱动、追求首屏体积 |
| stylex | 编译期原子化 / 零运行时 | `stylex.create` + `stylex.props` | 中：受限语法，推荐 Token | 编译成原子类，运行时极薄 | 性能敏感、跨 Web/Native 代码复用 |
| vanilla-extract | 编译期 / 零运行时 | `style`/`createVar` TS API | 中：静态值 + 变量 | 生成静态 CSS，引入 className | 追求零 runtime、与构建深度集成 |
| Linaria | 编译期 / 零运行时 | `css`/`styled` 模板字符串 | 弱：表达式需可静态求值，props 通过切换 class | 生成静态 CSS，JS 仅类名映射 | 想要 CSS-in-JS 写法但首屏/SSR 预算敏感 |

### 写法与产物对照

- 运行时（styled-components/Emotion）：
  - 写法：模板字符串或对象样式，允许使用 props / theme 计算样式；开发态插入 `<style>`，生产态可能提取 critical CSS。
  - 产物：JS bundle + 内联 style 标签，类名在运行时生成（`sc-abc123`），首屏注水与 HMR 需要样式注入开销。
- 编译期（Linaria/vanilla-extract）：
  - 写法：受限的模板字符串或 TS API（`css`/`style`），编译器提前求值并生成 `.css`，JS 中只保留 `className` 映射。
  - 产物：静态 CSS 文件（或内联 chunk）+ 极薄的 className 映射，运行时不再注入 style，SSR 直接 link CSS。

### Linaria 示例（编译期）

源码（编译前）：

```tsx title="card.tsx"

const card = css`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  background: white;
  transition: box-shadow 150ms ease;

  &:hover {
    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
  }
`

export function Card({ children }: { children: React.ReactNode }) {
  return <section className={card}>{children}</section>
}
```

编译产物（示意）：

```css title="card.linaria.css"
.card_h3dj1z {
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  background: white;
  transition: box-shadow 150ms ease;
}
.card_h3dj1z:hover {
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
}
```

```js title="card.tsx (compiled excerpt)"

const card = 'card_h3dj1z'
export function Card({ children }) {
  return <section className={card}>{children}</section>
}
```

特点：CSS 被提前生成，JS 仅保留类名字符串；运行时不再注入 `<style>`，与传统静态 CSS 链路类似。

## 示例（styled-components）

```tsx

const Card = styled.section`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  box-shadow: ${({ elevated }) => (elevated ? '0 10px 30px rgba(0,0,0,0.06)' : 'none')};
`

const Button = styled.button`
  padding: 10px 16px;
  border-radius: 8px;
  border: 1px solid #111827;
  background: #111827;
  color: #fff;
  &:hover { background: #0f172a; }
`

export const Demo = () => (
  <Card elevated>
    CSS-in-JS
    动态样式，组件边界
    <Button>查看详情</Button>
  </Card>
)
```

### styled-components 的 SWC 插件提示

`@swc/plugin-styled-components`（或 Next.js `compiler.styledComponents`）在编译阶段处理标签模板，保持运行时链路但优化可读性与 SSR 稳定性：

```json title=".swcrc"
{
  "jsc": {
    "experimental": {
      "plugins": [
        ["@swc/plugin-styled-components", { "displayName": true, "ssr": true, "minify": true, "pure": true }]
      ]
    }
  }
}
```

- `displayName`：开发态易调试；`ssr`：确保类名/注入顺序稳定，减少水合不一致。
- `minify`/`pure`：压缩模板输出，帮助摇树减轻运行时体积，但依旧属于运行时注入流派。

## 常见坑与对策

- 运行时体积：优先选择编译模式或零运行时方案（如 vanilla-extract），或开启 Babel SWC 优化。
- SSR 注水：衡量首屏样式注入体积；必要时提取静态样式或开启样式缓存。
- 类名调试：在开发环境打开 displayName/label；在生产环境启用最小化。
- HMR 性能：减少过深的动态表达式；拆分组件，降低热更范围。

---

## CSS Modules / Scoped 阶段

<TailwindTopicHero topicId="tailwindcss/history/history-css-modules" title="CSS Modules / Scoped 阶段" />

## 要点

- 类名哈希化实现作用域隔离，天然防止全局污染；适合可发布组件库。
- 复用靠共享变量/混入文件，跨组件复用需要额外抽象；主题切换需额外 token 管线。
- 适合中大型 Web 应用或组件库，需要隔离但不想引入运行时。
- 代表性包/工具链：`webpack css-loader modules`、`Vite + vite:css-modules`、`Next.js` 内置 CSS Modules 支持、`vanilla-extract`（零运行时但同属编译期 CSS 模块流派）、Vue `<style scoped>`（为选择器自动加 `data-v-*` 的同类方案）、Svelte `<style>`（自动注入 `svelte-xxx` 选择器）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 隔离性好；无运行时；与 React/Vue 配合顺畅 |
| 劣势 | tokens/主题需额外管线；跨组件样式复用需要谨慎抽象 |
| 适用 | 设计体系尚未 token 化、但需要隔离的组件库/应用 |
| 不适用 | 需要跨平台（小程序）共享原子类，或希望直接用 Utility-first 的团队 |

## 代表性包与用法

- **webpack / Vite CSS Modules**：在 bundler 中开启 `modules`，生成哈希类名；可结合 `:global` 暴露公共样式。

```js title="Vite 配置示例 vite.config.ts"
export default defineConfig({
  css: {
    modules: {
      localsConvention: 'camelCase',
      generateScopedName: '[name]__[local]___[hash:base64:5]',
    },
  },
})
```

- **Next.js / CRA 默认支持**：在 `.module.css`、`.module.scss` 文件中书写样式，自动作用域隔离。

```tsx title="Next.js 页面使用 CSS Modules"

export default function Page() {
  return Next.js 带来的开箱隔离
}
```

- **vanilla-extract**：编译期生成 CSS，暴露 `className` 与变量，零运行时，常用于对性能要求高的组件库。

```ts title="vanilla-extract" 
// styles.css.ts

export const primary = createVar()
export const card = style({
  borderRadius: '16px',
  vars: { [primary]: '#111827' },
  border: `1px solid color-mix(in srgb, ${primary} 10%, transparent)`,
})
```

## Vue `<style scoped>`（同属编译期作用域流派）

- **原理**：SFC 编译时为模板节点与样式选择器都添加 `data-v-xxxx`，使样式仅作用于当前组件渲染的 DOM。
- **示例**：

```html
<template>
  <section class="card">
    Scoped
    {{ title }}
  </section>
</template>

<style scoped>
.card { @apply rounded-xl border bg-card/80 p-4; }
.eyebrow { @apply text-xs uppercase tracking-[0.2em] text-muted-foreground; }
</style>
```

- **产物**：`.card[data-v-xxxx] { ... }`，节点渲染为 `<section class="card" data-v-xxxx>`。
- **适用/注意**：适合 Vue 组件局部隔离；若需全局样式或第三方组件穿透，使用 `:global`/`::v-deep`；可与 Tailwind `prefix` 叠加以减少宿主覆盖。

## Svelte `<style>` 默认隔离

- **原理**：Svelte 编译器为组件生成唯一标识（如 `svelte-abc123`），并将其附着在 DOM 与样式选择器上，效果类似 scoped。
- **示例**：

```html
<script>
  export let title = 'Svelte Scoped'
</script>

<section class="card">
  {title}
</section>

<style>
  .card {
    border: 1px solid #e5e7eb;
    border-radius: 16px;
    padding: 16px;
  }
</style>
```

- **产物**：编译后节点为 `<section class="card svelte-abc123">`，CSS 为 `.card.svelte-abc123 { ... }`。
- **适用/注意**：默认即可隔离，跨组件共用样式需 `:global(.class)`；如叠加 Tailwind，可直接在模板写原子类或在 `<style>` 中 `@apply`（需配置）。在微前端/嵌入场景仍可与 `prefix`/命名空间组合。

## 示例（React）

```tsx title="Card.tsx"

export function Card() {
  return (
    <section className={`${styles.card} ${styles.elevated}`}>
      
        CSS Modules
        作用域隔离
        类名哈希化，不会与全局冲突。
        <button className={styles.button}>查看详情</button>
      
    </section>
  )
}
```

```css title="Card.module.css"
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
.elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.header { display: flex; flex-direction: column; gap: 8px; }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
```

## 常见坑与对策

- 主题/多品牌：通过 CSS 变量承载 tokens，再在 Modules 中引用，减少全局文件。
- 复用：抽出 `variables.css` 与 `mixins.css`，避免在多个模块重复定义色板与间距。
- 动态类：避免在运行时拼接哈希类，统一在模块里声明必要的修饰类。
- 与 Utility-first 协作：可在 Modules 内少量 `@apply`（若配置允许），或在过渡期同时保留 atomic 辅助类。

---

## 生成式 CSS / 原生能力融合

<TailwindTopicHero topicId="tailwindcss/history/history-future-generative-css" title="生成式 CSS / 原生能力融合" />

## 要点

- 核心思想：CSS 将越来越生成式——tokens/设计意图 → 构建器/AI 生成规则 → @layer/@scope 限界 → 运行时仅保留需要的原子或组件级片段。
- 原生能力上收：`@container`、`:has()`、`@scope`、`@property`、`color-mix()` 让布局/状态/主题更多在 CSS 层解决，减少 JS 占用。
- 规则协同：`@layer` 控制覆盖顺序，`@scope` 限制影响面，`@container` 驱动响应式组件，`@property` 让自定义属性可动画、可类型化。
- 生态趋势：Tailwind/UnoCSS 等生成器与原生新特性融合，JIT/摇树继续演化；AI 生成需要「白名单 tokens + 层级约束 + lint」闭环。

## 未来能力组合（示意）

```css title="future.css"
@layer reset, theme, components, utilities;

@layer theme {
  @property --radius-lg {
    syntax: '<length>';
    inherits: false;
    initial-value: 16px;
  }

  :root {
    --brand: color-mix(in srgb, #0ea5e9 60%, #111827 40%);
  }
}

@layer components {
  @scope (.card) {
    .card {
      border-radius: var(--radius-lg);
      border: 1px solid color-mix(in srgb, var(--brand) 30%, #e5e7eb 70%);
      background: white;
      transition: box-shadow 150ms ease, transform 150ms ease;
    }

    @container style(--wide: min-width: 640px) {
      .card { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
    }

    .card:has(button:focus-visible) { box-shadow: 0 12px 40px rgba(0,0,0,0.08); }
  }
}
```

- `@layer`：把生成产物分层，便于 merge/覆盖与分析。
- `@scope`：限制作用域，避免全局污染；可以与组件入口 class 对齐。
- `@container`：让组件按父容器而非视口响应式，适合卡片/区块。
- `@property`：声明式类型化，配合 tokens/动画避免 “数字魔法值”。

## 生成式流水线设想

1. 设计源：设计稿/Design Token/接口协议输出 JSON（颜色、间距、阴影、配色模式）。
2. 生成阶段：脚本或 AI 根据 tokens + 组件意图生成 `@layer theme/components/utilities`，只产出命中的规则；原子类生成器继续提供 JIT，辅以 `content` 精准扫描。
3. 约束阶段：lint 检查 `@scope` 边界、动态类白名单、`@property` 类型；merge 规则防止类冲突。
4. 运行时：`@container`/`:has()`/`color-mix()` 在浏览器内完成适配，JS 仅负责交互或数据绑定。
5. 反馈：覆盖率/体积监控回写到生成器，调整 tokens 或 layer 顺序。

> 这条链路的目标是「声明意图→生成→约束→运行」，开发者关注 tokens 与交互，而不是手写长链选择器。

## 对现有工具链的启示

- Tailwind/UnoCSS：保留原子类生态，但补充 `@layer`/`@scope` 输出选项，配合容器查询 preset；JIT 应能理解 `@property`/`color-mix()`。
- RSC/小程序场景：通过预编译生成层化 CSS，运行时只使用容器查询/自定义属性，避免 JS 注水。
- 设计系统：tokens 需要类型（color, length, angle），与 `@property` 对齐；AI 生成 prompt 应包含「可用 tokens」「允许的 layer」清单。

## 更多未来方向与落地思考

- 多维适配：容器查询 + 视口查询 + 环境查询（prefers-reduced-motion、HDR/dynamic-range）组合，减少 JS 监听 resize 的需求。
- 层级版本化：把 `@layer` 视作 “样式 API”，为主题/品牌定制留出独立层，避免升级时破坏核心组件层。
- 作用域化 Islands：`@scope` 与路由/微前端边界绑定，配合 `:has()` 处理局部交互，降低全局选择器对不同应用的干扰。
- 类型化 tokens：通过 `@property` 为长度/颜色/角度声明类型，结合 design-token JSON schema，让生成器/AI 在编译期就能发现非法取值。
- CSS Houdini 与动画：自定义属性 + paint/worklet 组合，替代 JS 动画；配合 `view-transition` 等 API，把 UI 过渡交给浏览器管线。
- 生成式护栏：为 AI/脚本提供 “允许的 tokens + 层级 + scope 边界” 的提示词或配置，输出后再用 lint/visual diff 校验，形成闭环。

## 进一步阅读

- https://developer.mozilla.org/en-US/docs/Web/CSS/@scope
- https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries
- https://developer.mozilla.org/en-US/docs/Web/CSS/@property
- https://tailwindcss.com/blog/tailwindcss-v4-alpha

---

## Token 化与 Headless 组件阶段

<TailwindTopicHero topicId="tailwindcss/history/history-headless-tokens" title="Token 化与 Headless 组件阶段" />

## 要点

- API 与样式解耦的 Headless 组件（Radix、Headless UI、shadcn/ui、reka-ui）+ Tailwind/Uno，让设计 token 可直连类名。
- `cva`/`tailwind-variants` 集中声明 variants/default/compound，配合 `tailwind-merge` 兜底；最利于 AI/脚本生成。
- 适合多品牌/暗色/大规模设计体系；前提是 tokens、lint/merge/评审链到位。
- 代表性包：Primitives（`@radix-ui/react-*`、`@ark-ui/react`、`@zag-js`）、Headless 组件库（`@headlessui/react`）、样式模板化方案（`shadcn/ui`、`reka-ui`、`vaul`），加上 class 构造器（`class-variance-authority`、`tailwind-variants`、`tailwind-merge`）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | API 与样式分离；变体集中；对 AI/自动化友好；跨品牌/主题低成本 |
| 劣势 | 需要维护 token 表与规范；初学者心智负担高；文档/范式建设成本高 |
| 适用 | 需要统一体验、多产品线、多主题/品牌、希望自动化生成 UI 的团队 |
| 不适用 | 极简站点或无设计体系、无法投入规范建设的团队 |

## 什么是 token？什么是 token 化

- **Design Token**：把颜色、间距、圆角、字号、阴影、动效等设计属性抽象成命名变量（如 `color-primary-500`、`radius-lg`），集中管理，作为唯一取值来源。
- **Token 化**：将设计稿中的具体数值（#123456、18px 等）转译为 token 名称，在代码/样式里只引用 token，不写裸值；同时保留映射表与校验链，确保所有取值来自 token。
- **落地方式**：
  - CSS 变量：`:root { --color-primary-500: #2563eb; --radius-lg: 12px; }`，配合 Tailwind `@theme` 或自定义 theme 读取。
  - Tailwind 配置：在 `theme.colors/spacing/radius` 中声明，生成对应原子类。
  - 多主题/多品牌：通过 `data-theme` 或类名切换一组 token 变量，实现暗色/品牌切换而不改组件逻辑。
- **收益**：统一视觉取值，减少随手取值漂移；便于 lint/merge/脚本校验；支持跨品牌/主题的快速切换。
- **注意**：token 只是基石，还需 `cva`/`tailwind-variants` 把 token 编织成变体，再由 Headless 组件消费。

## 代表性包与组合方式

- **Radix Primitives / Ark UI**：提供无样式、可访问性完善的组件原件。

```tsx title="Radix + Tailwind"

export function TabsDemo() {
  return (
    <Tabs.Root defaultValue="code" className="w-full">
      <Tabs.List className="inline-flex gap-2 rounded-lg bg-muted p-1">
        <Tabs.Trigger value="code" className="rounded-md px-3 py-2 text-sm data-[state=active]:bg-card data-[state=active]:shadow">
          代码
        </Tabs.Trigger>
        <Tabs.Trigger value="preview" className="rounded-md px-3 py-2 text-sm data-[state=active]:bg-card data-[state=active]:shadow">
          预览
        </Tabs.Trigger>
      </Tabs.List>
    </Tabs.Root>
  )
}
```

- **Headless UI**：Vue/React 可组合的无样式组件，常与 Tailwind 搭配。

```tsx title="Headless UI + Tailwind"

export function MenuDemo() {
  return (
    <Menu as="div" className="relative inline-block text-left">
      <Menu.Button className="inline-flex items-center gap-2 rounded-lg border px-3 py-2">操作</Menu.Button>
      <Menu.Items className="absolute right-0 mt-2 w-40 rounded-xl border bg-card p-2 shadow-xl">
        <Menu.Item>
          {({ active }) => <button className={`w-full rounded-lg px-3 py-2 text-sm ${active ? 'bg-muted' : ''}`}>编辑</button>}
        </Menu.Item>
      </Menu.Items>
    </Menu>
  )
}
```

- **shadcn/ui / reka-ui 模板化**：基于 Tailwind + `cva`/`tailwind-variants` 预置 class，直接复制到项目。

```tsx title="tailwind-variants 组合"

const badge = tv({
  base: 'inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium',
  variants: {
    tone: {
      neutral: 'bg-muted text-foreground',
      success: 'bg-emerald-50 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-100',
      danger: 'bg-rose-50 text-rose-700 dark:bg-rose-900/30 dark:text-rose-100',
    },
  },
  defaultVariants: { tone: 'neutral' },
})

export function Badge({ asChild, className, ...props }: { asChild?: boolean } & React.HTMLAttributes<HTMLElement>) {
  const Comp = asChild ? Slot : 'span'
  return <Comp className={cn(badge(props), className)} {...props} />
}
```

##  tokens → variants → primitives 流程（示意）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart TD
  Tokens["设计 Token: color / space / radius / typography"] --> Factory["cva/tv 工厂: size / variant / state"]
  Factory --> Primitives["Headless / Primitives 组件"]
  Primitives --> UI["业务组件组合"]
  Tokens --> Lint["lint / merge 校验，防止越界取值"]
```

  
    
    Tokens：统一色板/间距/圆角/排版，作为唯一取值来源。
  
  
    
    Factory：用 cva/tv 把尺寸、语义、状态集中声明。
  
  
    
    Primitives/UI：Headless 组件消费变体，组合成业务 UI。
  
  
    
    Lint/Merge：校验取值合法，合并类名，防止越界与冲突。
  

## 示例（Button with cva，React）

```tsx

const button = cva(
  'inline-flex items-center gap-2 rounded-lg border bg-primary px-4 py-2 text-sm text-primary-foreground shadow-sm transition',
  {
    variants: {
      variant: { default: '', outline: 'bg-transparent text-foreground border-border', ghost: 'bg-transparent hover:bg-muted' },
      size: { sm: 'h-8 px-3', md: 'h-10 px-4', lg: 'h-11 px-5' },
    },
    compoundVariants: [{ variant: 'outline', size: 'lg', class: 'shadow-none' }],
    defaultVariants: { variant: 'default', size: 'md' },
  }
)

export function Button({ className, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
  return <button className={cn(button(props), className)} {...props} />
}
```

## 对齐建议

- tokens：颜色/间距/圆角/阴影/字号写成 tokens（CSS 变量或 `@theme`），保持「设计稿 → token 名」映射。
- variants：所有状态/尺寸/语义集中到工厂（`cva`/`tv`），业务组件只消费 builder；默认值写死。
- merge：统一使用 `cn`（含 `tailwind-merge`）兜底，避免 class 冲突。
- 资产：记录推荐组合（例如按钮/表单/卡片的标准类名），便于 AI/新人沿用。

---

## Sass / Less 预处理阶段

<TailwindTopicHero topicId="tailwindcss/history/history-preprocessors" title="Sass / Less 预处理阶段" />

## 要点

- 变量/混入/函数提升复用度，BEM/OOCSS 更易落地；仍是全局作用域。
- 嵌套与继承易失控，编译体积可能膨胀；设计 token 对齐仍需额外规范。
- 适合有一定复用需求但尚未组件化的团队，或需快速落地主题的中小项目。
- 代表性包：`Sass/SCSS`（社区最强，`node-sass`/`dart-sass` 编译器）、`Less`（Ant Design 时代的主题变量代表）、`Stylus`（函数式写法灵活）、`PostCSS`（通过插件完成 autoprefixer、nesting）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 变量/混入提升复用；工具链成熟；CSS 输出可控 |
| 劣势 | 仍是全局污染；嵌套地狱；主题切换需额外管线 |
| 适用 | 中小型项目、需要少量主题切换或设计稿映射 |
| 不适用 | 需要强隔离/可发布组件库、希望直接对齐 tokens 的项目 |

## 代表性包与常见场景

- **Sass/SCSS**：主流功能最全，配合 `@use`/`@forward` 进行模块化。
- **Less**：变量 + 计算的主题切换（Ant Design `modifyVars`）经典用法；仍然是全局样式。
- **Stylus**：缩进语法 + 函数式 mixin；在 Vue 早期模板中常见。
- **PostCSS 插件链**：`autoprefixer` + `postcss-nesting` 组合，在不迁移到 CSS-in-JS 的情况下获得新语法支持。

```scss title="Sass 模块化 tokens"
// tokens/_color.scss
$primary: #111827;
$muted: #6b7280;

// tokens/_radius.scss
$card-radius: 16px;

// styles/card.scss
@use '../tokens/color' as *;
@use '../tokens/radius' as *;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $card-radius;
}
```

```less title="Less modifyVars 快速主题切换"
// 通过 webpack/vite 调整 modifyVars
lessOptions: {
  javascriptEnabled: true,
  modifyVars: {
    '@primary-color': '#111827',
    '@btn-border-radius-base': '8px',
  },
}
```

```css title="PostCSS 插件链 (postcss.config.js)">
module.exports = {
  plugins: {
    'postcss-nesting': {},
    autoprefixer: {},
  },
}
```

## 示例（Sass + BEM）

```scss
$radius: 16px;
$primary: #111827;
$muted: #6b7280;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $radius;
  padding: 16px;
  &--elevated { box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06); }
  &__header { display: flex; flex-direction: column; gap: 8px; }
}

.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: $muted; }
.btn {
  padding: 10px 16px;
  border-radius: $radius - 4px;
  border: 1px solid $primary;
  background: $primary;
  color: #fff;
  &:hover { background: darken($primary, 5%); }
}
```

## 常见坑与对策

- 嵌套层级：限制在 3 层以内；通过 lint 阻止深层选择器。
- 变量散落：集中 tokens 到单一文件，防止多处色板分叉。
- 产物体积：避免滥用 `@extend` 与全局混入；定期检查编译后大小。
- 迁移路径：提前用 CSS 变量承载 tokens，便于未来切到 Utility-first/组件化。

---

## Raw CSS / BEM / OOCSS

<TailwindTopicHero topicId="tailwindcss/history/history-raw-css" title="Raw CSS / BEM / OOCSS" />

## 要点

- 全局样式 + 命名约定（BEM/OOCSS）降低心智负担，工具链简单。
- 成本：覆盖链条难排查、命名冲突频发，复用依赖团队纪律。
- 适合一次性页面/静态站点或极小体量项目；越过一定规模后维护成本陡增。
- 代表性包：`normalize.css`/`reset.css` 负责基线统一，`Bootstrap 3/4` 带着 "组件 + 全局样式" 的典型模式，`Pure.css`/`Bulma` 以小体积展示了语义化 class 的上限。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 无构建依赖，浏览器直读；类名语义清晰；入门成本低 |
| 劣势 | 全局污染；覆盖顺序难控；难对齐 design token；重复样式多 |
| 适用 | Landing/活动页、小型展示站点；无复杂主题/状态需求 |
| 不适用 | 中大型应用、需要强隔离或多主题的项目 |

## 代表性包与典型用法

- **normalize.css / reset.css**：放在入口，统一不同浏览器的默认样式；之后才叠加自己的命名体系。

```html title="入口引入"
<link rel="stylesheet" href="/static/normalize.css" />
<link rel="stylesheet" href="/static/site.css" />
```

- **Bootstrap 3/4**：全局命名 + 组件样式绑定，适合快速拼页面。

```html title="Bootstrap 卡片"
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4/dist/css/bootstrap.min.css" />

  
    Bootstrap
    全局 + 组件绑定
    通过 utility 辅助类和组件 class 组合完成 UI。
    <button class="btn btn-dark">查看详情</button>
  

```

- **Bulma / Pure.css**：语义化 class + 轻量体积，适合无需强定制的小站点。

```html title="Bulma 按钮示例"
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css" />

  <button class="button is-dark">Dark</button>
  <button class="button is-outlined is-dark">Outline</button>
  <button class="button is-light">Light</button>

```

## 示例（BEM）

```html
<section class="card card--elevated">
  <header class="card__header">
    Raw CSS
    简单但全局
    命名靠约定，覆盖与复用全靠纪律。
    <button class="btn btn--primary">查看详情</button>
  </header>
</section>

<style>
  .card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
  .card--elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
  .card__header { display: flex; flex-direction: column; gap: 8px; }
  .card__eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
  .card__title { font-size: 18px; margin: 0; }
  .card__desc { color: #4b5563; font-size: 14px; }
  .btn { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
  .btn--primary:hover { background: #0f172a; }
</style>
```

## 常见坑与对策

- 命名冲突：统一前缀或分块（如 `layout-`/`component-`）。
- 覆盖链条：禁止超过 3 层嵌套；避免 `!important` 堆叠。
- 设计对齐：提前抽出色板/间距变量，即便是 CSS 变量也能减少漂移。
- 可维护性：为组件化迁移预留出口（拆分局部文件，减少跨文件覆盖）。

---

## Utility-first / Tailwind / UnoCSS 阶段

<TailwindTopicHero topicId="tailwindcss/history/history-utility-first" title="Utility-first / Tailwind / UnoCSS 阶段" />

## 要点

- 类名即样式，JIT + content 精准摇树；与设计 tokens/variants 易对齐。
- 生态差异：Tailwind（插件/merge/社区资产） vs UnoCSS（高度自定义、需自养规则）。
- 风险：可读性、class 爆炸、content 过宽、动态类失控；需要 tokens/variants/merge 的约束。
- 代表性包：`Tailwind CSS`（JIT + 官方插件）、`Windi CSS`（早期即时模式）、`UnoCSS`（preset/attributify + 自定义规则）、`twin.macro`（将 Tailwind 写在 CSS-in-JS 内）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 低认知切换；JIT 产物小；生态丰富；与 Headless 组合好 |
| 劣势 | 约束缺失时可读性差；动态类膨胀；需 lint/merge/评审配合 |
| 适用 | 高迭代速度、需要设计体系对齐、跨端/多产品线场景 |
| 不适用 | 极简静态站点、无法建立 tokens/规范的团队 |

## 代表性包与用法

- **Tailwind CSS**：官方插件/merge/IDE 提示最完善，适合团队基线。

```js title="tailwind.config.ts"
export default {
  content: ['./src/**/*.{ts,tsx,html}'],
  theme: {
    extend: {
      colors: { brand: '#111827' },
      borderRadius: { xl: '16px' },
    },
  },
  plugins: [require('@tailwindcss/typography'), require('@tailwindcss/forms')],
}
```

- **UnoCSS**：preset + 自定义规则；`attributify` 让属性即类名。

```ts title="UnoCSS 配置 unocss.config.ts"

export default defineConfig({
  presets: [presetUno(), presetAttributify(), presetIcons()],
  rules: [['btn', { padding: '10px 16px', 'border-radius': '8px', background: '#111827', color: '#fff' }]],
})
```

```html title="UnoCSS attributify"
<section grid gap-3 rounded-2xl border p-4 shadow-sm>
  UnoCSS
  Attributify + Preset
  <button btn hover="bg-#0f172a">查看详情</button>
</section>
```

- **twin.macro**：在 styled-components/Emotion 中写 Tailwind，兼顾原子化与 CSS-in-JS 开发体验。

```tsx title="twin.macro"

const Card = styled.section(() => [tw`grid gap-3 rounded-2xl border bg-white/80 p-4 shadow-sm`])

export function TwinDemo() {
  return (
    <Card>
      twin.macro
      Tailwind 写在 CSS-in-JS 里
    </Card>
  )
}
```

##  JIT 摇树流程示意

```mermaid
%%{ init: { "sequence": { "mirrorActors": false } } }%%
sequenceDiagram
  participant Source as "模板源码"
  participant Scanner as "content 扫描"
  participant JIT as "JIT 生成器"
  participant CSS as "精简 CSS 产物"
  Source->>Scanner: "扫描类名（含 cva/tv 静态值）"
  Scanner->>JIT: "传递匹配到的原子类"
  JIT-->>CSS: "生成仅用到的规则"
  CSS-->>Source: "产出 build 结果，摇树完成"
```

  
    
    Scanner：只扫描模板里的静态类名（含 cva/tv 输出），避免 content 过宽。
  
  
    
    JIT：按需生成规则，删除未命中的原子类。
  
  
    
    产物：构建出的 CSS 只保留使用过的类，体积可控。
  

## 示例（Tailwind 基础卡片）

```tsx
export function TailwindCard() {
  return (
    <section className="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
      Tailwind
      类名即样式
      JIT + tokens；类名一目了然，摇树后产物小。
      <button className="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
        查看详情
      </button>
    </section>
  )
}
```

## Tailwind vs UnoCSS（补充要点）

- 生态：Tailwind 拥有 typography/forms/animate 等插件、`tailwind-merge`、丰富的 preset 和组件范式；UnoCSS 更灵活但规则/merge/IDE 提示需自养。
- 类型提示：Tailwind 官方 language-service 覆盖全面；UnoCSS 依赖 preset/插件质量。
- Merge 去重：Tailwind 配合 `tailwind-merge` 规则完善；Uno 默认不处理 class 去重，需要自定义。
- 运行时：Tailwind v4 产物稳定，适配 RSC/SSR；UnoCSS 即时模式极快，适合高度定制。

## 常见坑与对策

- content 过宽：精确到模板目录，避免全局通配导致产物膨胀。
- 动态类：优先 `cva`/`tailwind-variants` 参数化，禁用字符串自由拼接。
- 可读性：建立 tokens/variants/推荐组合，评审时对齐；必要时为复杂关系类加注释。
- 体积：构建后查看 CSS 体积或浏览器 Coverage；必要时开启分析工具。
- 设计稿映射：把常用 spacing/颜色/圆角提炼为设计 token，并在 `cva` 默认值上锁定，避免“随手取值”。

---

## 样式方案的演化

<TailwindTopicHero topicId="tailwindcss/history/history-style-evolution" title="样式方案的演化" />

## 要点

- 这页不是为了背历史，而是为了回答一个现实问题：为什么今天越来越多团队会走向原子化 CSS。
- 样式方案的主流实践，整体确实从「全局命名」走向「模块化 / 组件化」再到更强的组合化与原子化，但这更像常见演进路径，而不是所有团队都遵循的一条单线历史。
- 原子化 CSS 的价值不只在于写得快，更在于它更适合和 tokens、JIT、组件变体、AI 生成这些现代工作流接起来。
- 但它也不是终点。多 runtime（Web、RSC、小程序）场景下，真正稳定的核心通常是 token、组件边界与构建约束，而不是某一种具体写法。

## 建议怎么读这页

- 如果你在做技术选型，重点看“各阶段优势 / 劣势 / 适用场景”。
- 如果你在做团队分享，重点看时间轴和“原子化 CSS 解决 / 未解决的问题”。
- 如果你已经决定用 Tailwind，这页可以帮助你向团队解释“为什么要建立约束”，而不只是说它流行。

> 组件库部分已拆为独立页面：[组件库的演进](/docs/tailwindcss/history/component-evolution)。
>
> 说明：这页的时间线更适合看作“常见演进路径”。截至 2026 年 2 月 27 日更新的 Next.js 官方文档，仍把 Tailwind CSS、CSS Modules、Global CSS、Sass 与 CSS-in-JS 并列列为当前可选方案，而不是线性替代关系。

:::info 资料参考
- [Next.js: How to use CSS in your application](https://nextjs.org/docs/app/getting-started/css)
- [Next.js: CSS Modules](https://nextjs.org/docs/14/app/building-your-application/styling/css-modules)
- [State of CSS 2024: Tools](https://2024.stateofcss.com/en-US/tools/)
:::

##  样式方案时间轴

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 32, "rankSpacing": 24 } } }%%
flowchart TB
  A["2010 · Raw CSS / BEM / OOCSS"]
  B["2013 · 预处理器 Sass/Less，变量/混入，BEM 体系化"]
  C["2015 · CSS Modules，局部作用域"]
  D["2017 · CSS-in-JS（styled-components/Emotion），组件边界 + 运行时成本"]
  E["2020 · Utility-first (Tailwind/Windi/Uno)，JIT、摇树优化、设计 token 对齐"]
  F["2024 · tokens、构建期样式与多 Runtime（Web/RSC/Mini Program）协作"]

  A --> B --> C --> D --> E --> F
```

  
    
    2010：Raw CSS / BEM / OOCSS，语义命名 + 手写层级。
  
  
    
    2013：Sass/Less 变量与混入，BEM 体系化。
  
  
    
    2015：CSS Modules 作用域隔离。
  
  
    
    2017：CSS-in-JS，组件边界 + 运行时成本。
  
  
    
    2020：Utility-first，JIT、摇树、tokens 对齐。
  
  
    
    2024：tokens、构建期样式与多 Runtime 协作继续加强。
  

### 几段常见的「升级理由」

以下更适合被理解为常见驱动力，而不是所有团队都会经历的统一迁移路径。

- BEM 项目重构时，遇到 `.btn--primary` 在四个文件里被覆盖，且 hover 颜色不一致；引入 Utility-first 后把按钮拆成变体，类名归到 `cva` 工厂，审阅时一眼能看出状态组合。
- CSS-in-JS 方案在 SSR 下首屏注水 60KB，改为 Tailwind + tokens 后，首屏 CSS 控制在 8KB 以内，且通过 `content` 精准扫描避免动态膨胀。
- Mini Program 场景 class 长度有限，原子类 + 预生成模板替换了动态拼接的 style 字符串，稳定性提高，构建速度更快。

## 常见误解

- 不要把这页理解成“行业已经按这条路线完成替代”。现实情况更接近多种方案长期并行，只是在不同阶段和场景里，团队更容易走上这条路径。
- 不要把“Utility-first 更流行”理解成“CSS Modules、Sass、CSS-in-JS 已经过时”。它们在组件库、内容站、遗留系统和特定框架生态里仍然非常常见。
- 不要把 `Headless + tokens` 理解成一种新的样式语言。它更像设计系统与组件抽象的分层方式，可以和多种样式方案组合。

## 各阶段优势 / 劣势 / 适用场景

如果你是手机上快速扫读，这里先看这 6 条就够了：

- `Raw CSS + BEM/OOCSS`：最直观，适合小体量页面；问题是全局污染和命名漂移。
- `Sass/Less`：复用能力更强，适合还没进入组件化的项目；问题是仍然容易掉进全局和嵌套地狱。
- `CSS Modules`：隔离更好，适合中大型项目和组件库；问题是跨组件复用和主题切换会更依赖额外抽象。
- `CSS-in-JS`：动态能力强，适合主题和状态很多的设计系统；问题是运行时、编译链和体积成本更高。
- `Utility-first`：迭代快、与 tokens 对齐、生态强；问题是没有约束时很容易 class 漂移。
- `Token + Headless`：这不是单独的样式范式，更像与多种样式方案并行发展的组件封装趋势；优点是更适合统一体验和 AI 协作，代价是必须认真维护 design system。

如果你需要更细一点的判断，可以看下面这份分段版速查：

### Raw CSS + BEM/OOCSS

- 优势：简单直观，命名自带语义。
- 劣势：全局污染明显，样式覆盖难排查，复用能力弱。
- 适用：小体量页面、低复杂度站点。
- 规避：先定前缀和命名规则，避免长选择器链。

### 预处理器（Sass / Less）

- 优势：变量、混入、函数提高复用，BEM 更容易落地。
- 劣势：仍然是全局样式，容易出现嵌套地狱和编译体积膨胀。
- 适用：需要一定复用，但还没有强组件边界要求的项目。
- 规避：限制嵌套层级，lint 禁止 `#id` 和深层选择器，保持色板集中。

### CSS Modules

- 优势：作用域隔离明确，天然减少全局污染。
- 劣势：样式与组件绑定更紧，跨组件复用和主题切换要额外抽象。
- 适用：中大型应用、可发布组件库、需要样式隔离的项目。
- 规避：抽 shared variables，避免在组件里声明全局变量。

### CSS-in-JS

- 优势：组件边界天然清晰，适合强动态样式和主题系统。
- 劣势：运行时和编译链更复杂，类名可读性通常较弱。
- 适用：需要强动态样式、多品牌、多主题的设计系统。
- 规避：尽量选零运行时方案或编译模式，严格限制动态样式范围。

### Utility-first（Tailwind / Uno）

- 优势：低认知切换、JIT、摇树优化、与 tokens 对齐、生态丰富。
- 劣势：可读性高度依赖团队约束，`content` 不准时体积容易失控。
- 适用：高迭代速度、设计体系对齐、组件组合化明显的前后端或多端项目。
- 规避：建立 tokens 和 variants 规范，统一 `cn` + merge，禁止字符串拼类。

> 反过来说，内容型站点、低复杂度后台或强隔离组件库，也未必会把它当成默认最优解。

### Token + Headless 组件趋势

- 定位：它更像组件抽象与设计系统趋势，不是独立替代 Tailwind、CSS Modules 或 CSS-in-JS 的“下一代样式方案”。
- 优势：组件 API 与样式解耦，变体集中管理，适合统一设计语言。
- 劣势：需要持续维护 design system，没有约束时仍会漂移。
- 适用：多产品线、需要可插拔主题、希望被 AI 或脚本稳定消费的团队。
- 规避：维护 tokens 表，评审类名和变体工厂，保留 merge / lint 校验链。

> 参考方向：`Headless UI`、`Radix Primitives`、`shadcn/ui` 这类方案，本质上更偏组件抽象与设计系统分层，而不是单独的样式语言。

> 迁移建议：如果已有 CSS Modules/组件库想拥抱原子化，可先将公共 tokens 抽出，再在 Headless 组件上叠加 `cva`/`tailwind-variants`，逐步替换局部样式。

## 深入阅读（按阶段拆分）

- [Raw CSS / BEM / OOCSS](/docs/tailwindcss/history/raw-css)
- [Sass / Less 预处理](/docs/tailwindcss/history/preprocessors)
- [CSS Modules 阶段](/docs/tailwindcss/history/css-modules)
- [CSS-in-JS 阶段](/docs/tailwindcss/history/css-in-js)
- [Utility-first / Tailwind / UnoCSS](/docs/tailwindcss/history/utility-first)
- [Token 化与 Headless 组件](/docs/tailwindcss/history/headless-tokens)
- [生成式 CSS / 原生能力融合](/docs/tailwindcss/history/future-generative-css)

## 阶段代表性包速览

- `Raw CSS`：`normalize.css`、`Bootstrap`、`Bulma`
  常见用法：全局命名 + 组件 class。
- `预处理器`：`Sass`、`Less`、`PostCSS`、`Stylus`
  常见用法：变量、混入、主题定制。
- `CSS Modules`：Vite / webpack modules、Next.js、`vanilla-extract`
  常见用法：作用域哈希、编译期隔离。
- `CSS-in-JS`：`styled-components`、`Emotion`、`JSS`、`vanilla-extract`
  常见用法：运行时或编译期动态样式。
- `Utility-first`：`Tailwind`、`Windi`、`UnoCSS`、`twin.macro`
  常见用法：JIT 原子类、attributify、宏模式。
- `Headless + tokens`：`Radix`、`Headless UI`、`shadcn/ui`、`tailwind-variants`
  常见用法：作为组件抽象层，和 Tailwind、CSS Modules、vanilla-extract 等方案配合。

## 阶段 Demo：把「方式」落到机制

### Raw CSS / BEM：零构建 + 约定

```html title="index.html"
<link rel="stylesheet" href="/reset.css" />
<section class="card card--elevated">
  Raw CSS
  全局命名
</section>
```

### 预处理器：脚本化编译与 tokens 复用

```json title="package.json"
{
  "scripts": {
    "build:css": "sass src/styles/index.scss dist/index.css --no-source-map && postcss dist/index.css -o dist/index.css",
    "watch:css": "sass --watch src/styles/index.scss:dist/index.css"
  }
}
```

```scss title="src/styles/index.scss"
@use './tokens' as *;
.card { border: 1px solid lighten($color-primary, 65%); border-radius: $radius-lg; }
```

### CSS Modules：编译期隔离 + 组件消费

```ts title="vite.config.ts"
export default { css: { modules: { generateScopedName: '[name]__[local]___[hash:base64:5]' } } }
```

```tsx title="Card.tsx"

export const Card = () => <section className={`${styles.card} ${styles.elevated}`}>CSS Modules</section>
```

### CSS-in-JS：主题运行时 + 编译模式

```tsx title="styled-components + ThemeProvider"

const theme = { primary: '#111827', radius: '12px' }
const Button = styled.button`border-radius: ${({ theme }) => theme.radius}; background: ${({ theme }) => theme.primary};`
export const Demo = () => <ThemeProvider theme={theme}><Button>动态主题</Button></ThemeProvider>
```

### Utility-first：Tailwind + cva 生成变体

```ts title="tailwind.config.ts"
export default { content: ['./src/**/*.{ts,tsx,html}'], theme: { extend: { colors: { brand: '#111827' } } } }
```

```tsx title="components/button.tsx"

const button = cva('rounded-lg px-4 py-2 text-sm font-medium', { variants: { tone: { brand: 'bg-brand text-white' } }, defaultVariants: { tone: 'brand' } })
export const Button = ({ tone = 'brand', ...props }) => <button className={button({ tone })} {...props} />
```

### Token + Headless：作为组件抽象层配合样式方案

```css title="src/styles/tokens.css"
:root { --color-primary: #111827; --radius-lg: 12px; }
[data-theme="dark"] { --color-primary: #e5e7eb; }
```

```tsx title="components/menu.tsx"

const item = tv({ base: 'flex items-center rounded-lg px-3 py-2 text-sm', variants: { active: { true: 'bg-muted text-foreground' } } })
export const MenuDemo = () => (
  <Menu>
    <Menu.Button className="rounded-lg border px-3 py-2">操作</Menu.Button>
    <Menu.Items className="mt-2 w-40 rounded-xl border bg-card p-2 shadow-xl">
      <Menu.Item>{({ active }) => <button className={item({ active })}>编辑</button>}</Menu.Item>
    </Menu.Items>
  </Menu>
)
```

###  决策树：选择样式方案

```mermaid
flowchart TD
  A["团队现状？"] --> B{"需要高度动态/多品牌吗？"}
  B -->|是| C["CSS-in-JS 或 Headless + Tailwind"]
  B -->|否| D{"已有 design tokens？"}
  D -->|有| E["Tailwind / Uno + tokens"]
  D -->|无| F["CSS Modules / Vue scoped 先隔离"]
  C --> G{"关注运行时/SSR 体积？"}
  G -->|是| H["Tailwind + cva/tv，减少运行时"]
  G -->|否| I["styled-components / Emotion 编译模式"]
  E --> J{"生态资产重要？"}
  J -->|重要| K["Tailwind（插件 / merge / 社区资产）"]
  J -->|不重要| L["UnoCSS（更灵活自定义）"]
```

## 语义化 vs 信息密度（跨方案视角）

- 语义化：类名、文件名、组件名是否能表达意图，调试时是否容易定位。
- 信息密度：同样的信息写了几次，是否集中在 tokens / variants，而不是散落在模板里。

快速判断可以直接看这几条：

- `Raw CSS / BEM`：语义化高，但信息容易分散。
- `预处理器`：复用比 Raw CSS 好，但容易把复杂度藏进嵌套里。
- `CSS Modules`：隔离性更强，语义主要靠组件名和文件名补偿。
- `CSS-in-JS`：动态能力强，但运行时方案通常信息密度一般。
- `Utility-first`：单个类名语义弱，但整体信息密度高，适合配合组件工厂。
- `Token + Headless`：语义和信息密度都高，但它更适合被理解为“设计系统与组件抽象层”，而不是单独的样式时代。

## 原子化 CSS 解决/未解决的问题

- ✅ 解决：
  - 认知负担：在很多场景里，类名即样式，减少模板与样式文件来回跳转。
  - 漂移与覆盖：通过更细粒度的类、`content` 扫描与组件工厂，减少一部分全局泄漏和重复声明。
  - 设计对齐：配合 tokens 与 variants，能让「设计 → 组件接口 / 类名」更容易建立映射。
- ⚠️ 风险：
  - 可读性：类名过长、无约束导致审阅困难。
  - 一致性：不同人随意取值，导致色板/间距失控。
  - 体积：动态类或 content 过宽会失去摇树收益。
- 🚫 不推荐直接作为唯一方案的场景：
  - 需要强隔离的可发布组件库（通常更适合 CSS Modules、vanilla-extract，或与 Tailwind 组合使用）。
  - 极简静态站点，对运行时无需求，模板类名冗长反而成本高。
  - 无法建立 design token/规范的团队，原子类易失控。

## 与运行时/平台的适配

- Web/RSC：优先静态生成、`content` 精准匹配 server 侧模板；避免在服务器计算随机类名。
- 小程序/多端：注意 class length 限制；预生成静态类，不依赖动态模板拼接。
- SSR/HMR：Tailwind v4 JIT 足够快；UnoCSS 具更灵活的即时模式，但生态/插件差异需权衡。

---

## 原子化 CSS 专题导览

<TailwindTopicHero topicId="tailwindcss/index" title="原子化 CSS 专题导览" />

## 为什么读这份专题

- 如果你刚接触原子化 CSS，这组文档会帮你先建立判断标准，再看工具细节，不会一上来就陷进类名和术语里。
- 如果你已经在用 Tailwind，这里重点回答三个实际问题：为什么团队会选它、怎样避免写乱、怎样让 AI 生成的代码还能被人读懂。
- 如果你正在维护多端或组件库项目，这里的内容会把 tokens、variants、merge、样式隔离这些概念串成一条完整链路，而不是零散技巧。

## 你会获得什么

- 一条更贴近现实的脉络：从样式方案的常见演进路径，到为什么 Tailwind 会成为近几年最常见的落地选择之一。
- 一套落地方法：怎么建立 tokens、怎么组织 variants、什么时候该用 `cva`/`tailwind-variants`、什么时候该停下来做约束。
- 一份可执行清单：如何评审 class、如何避免动态类失控、如何验证产物体积、如何把 AI 输出纳入可交付流程。
- 一组可直接参考的示例：React/Vue 的写法、组件封装方式，以及团队内部分享时能直接复用的对照材料。

## 这组文档适合谁

- 正在评估 Tailwind、UnoCSS、CSS Modules 等方案，想先看清取舍再决定的人。
- 已经在用 Tailwind，但发现代码开始变长、变乱、变难审阅，希望建立团队规范的人。
- 要做多端、小程序、组件库或 AI 辅助开发，想把“类名写法”升级成“工程工作流”的人。

## 建议阅读方式

### 第一次看

按这个顺序读：

1. [样式方案的演化](/docs/tailwindcss/history)
2. [Tailwind 设计理念](/docs/tailwindcss/tailwind-core)
3. [原子化 CSS 最佳实践](/docs/tailwindcss/best-practices)

先把“为什么会走到这一步”和“什么时候值得用”看明白，再进入具体技巧。

### 带着问题看

- 你在做技术选型：先看 [样式方案的演化](/docs/tailwindcss/history) 和 [Tailwind 设计理念](/docs/tailwindcss/tailwind-core)。
- 你在改现有项目：先看 [原子化 CSS 最佳实践](/docs/tailwindcss/best-practices) 和 [tailwind-merge、cva、tailwind-variants 精要](/docs/tailwindcss/merge-and-variants)。
- 你在处理隔离或嵌入场景：直接看 [样式隔离方案与原理](/docs/tailwindcss/style-isolation)。
- 你在做 AI 辅助开发：直接看 [AI 友好提示与 Demo 运行指南](/docs/tailwindcss/ai-friendly-and-demos)。

{/* ## 快速命令与讲稿提纲

- 安装依赖：`pnpm install`
- 运行 React Demo：`pnpm --filter react-app dev`；运行 Vue Demo：`pnpm --filter vue-app dev`
- 构建文档：`pnpm --filter website build`（或 `pnpm build:docs` 若存在别名）
- 若需拍照/截图：在对应页面保留 `<!-- screenshot: tailwindcss-{section} -->` 占位

参考提纲（45-60 分钟）：
- 开场（5m）：样式方案为何不断演进，展示时间轴与组件库演进。
- 原子化价值/风险（10m）：解决/未解决的问题 + 不适用场景。
- Tailwind 设计（10m）：JIT、variants、分层、插件与 `tailwind-merge`。UnoCSS 取舍。
- 最佳实践（10m）：tokens、`cva`/`tv`、关系类、性能/体积验证。
- AI 友好（10m）：提示模板、校验链，React/Vue 代码演示。
- Demo & Q&A（10-15m）：React/Vue 实机运行与对照代码。 */}

> 阅读建议：第一次读，优先把前 3 篇读完；已经在项目里踩过坑的人，可以直接从「最佳实践」和「merge / variants」开始。

## 导航总览

| 章节 | 适合什么时候看 | 你会带走什么 |
| --- | --- | --- |
| [样式方案的演化](/docs/tailwindcss/history) | 需要选型、做分享、统一团队认知时 | 明白原子化 CSS 是一条重要分支，但当前业界仍是多种方案并行共存 |
| [Tailwind 设计理念](/docs/tailwindcss/tailwind-core) | 想理解 Tailwind 本质时 | 看清 tokens、JIT、variants、组件 API 是怎样串起来的 |
| [原子化 CSS 最佳实践](/docs/tailwindcss/best-practices) | 要把 Tailwind 用稳时 | 建立一套可执行的约束、评审标准和常见场景写法 |
| [tailwind-merge、cva、tailwind-variants 精要](/docs/tailwindcss/merge-and-variants) | 组件开始出现变体和扩展点时 | 理解 merge、变体工厂和组件封装的边界 |
| [样式隔离方案与原理](/docs/tailwindcss/style-isolation) | 微前端、组件库、嵌入场景 | 判断什么时候该用 prefix、Modules、Shadow DOM 等方案 |
| [AI 友好提示与 Demo 运行指南](/docs/tailwindcss/ai-friendly-and-demos) | 想让 AI 参与产出 UI 时 | 把提示模板、校验链和运行示例接到工程里 |
| [各样式方案 Demo 与产物对照](/docs/tailwindcss/demos) | 需要演示或做对照实验时 | 直接看不同方案的代码、产物和差异 |

## 代码示例链接

:::tip 重点示例
**CSS 演进代码合集**：[css-history](https://github.com/sonofmagic/css-history) —— 按阶段收录 Raw CSS、预处理器、CSS-in-JS、Tailwind 等写法与产物截图，便于讲稿/对照演示时直接引用。
:::

## React/Vue 代码快速预览

<Tabs>
  <TabItem value="react" label="React (shadcn/ui 风格)">

```tsx

export function Hero() {
  return (
    
      
        Atomic CSS
        让设计系统与类名对齐
        `cva`/`tailwind-variants` 集中声明 variants，`tailwind-merge` 兜底合并，搭配 tokens 保持一致。
        
          <Button>开始体验</Button>
          <Button variant="secondary" className={cn('gap-1')}>
            预览代码
          </Button>
        
      
      
        <pre className="whitespace-pre-wrap">
{`const button = cva('inline-flex items-center px-4 py-2', {
  variants: { intent: { primary: 'bg-primary text-primary-foreground', ghost: 'hover:bg-accent' } },
  compoundVariants: [{ intent: 'primary', size: 'lg', class: 'shadow-lg' }],
})`}
        </pre>
      
    
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue (shadcn-vue/reka-ui 风格)">

```html
<script setup lang="ts">

</script>

<template>
  <section class="grid gap-4 rounded-2xl border bg-card/80 p-6 shadow-sm md:grid-cols-2">
    
      Atomic CSS
      组合变体，保持一致
      用 `cva` 或 `tailwind-variants` 宣告变体，再用 `cn`/`twMerge` 兜底。
      
        <Button>开始体验</Button>
        <Button variant="secondary" class="gap-1">预览代码</Button>
      
    
    
      <pre class="whitespace-pre-wrap">buttonVariants({ intent: 'primary', size: 'lg' })</pre>
    
  </section>
</template>
```

  </TabItem>
</Tabs>

---

## tailwind-merge、cva、tailwind-variants 精要

<TailwindTopicHero topicId="tailwindcss/merge-and-variants" title="tailwind-merge、cva、tailwind-variants 精要" />

## 要点

- `tailwind-merge` 负责 class 冲突/去重，是安全拼 class 的底座；推荐封装 `cn = twMerge(clsx(...))`。
- `cva`/`tailwind-variants` 把 variants/default/compound 集中声明，输出 class builder，避免状态散落；`tv` 内置 merge + slots，适合多槽组件。
- 闭环：tokens → 原子类/variants → builder → 组件 → content 扫描 → JIT → merge → 产物。

## 如果你只想先看结论

- 需要让组件接受 `className` 覆盖时，先把 `tailwind-merge` 接好。
- 单槽组件优先用 `cva`，多槽组件再考虑 `tailwind-variants`。
- 不要把 variants 散落在业务组件里，应该集中在 builder 文件里。

## 常见误解

- 不要把 `cva` 或 `tailwind-variants` 误解成 Tailwind 官方自带能力。它们是社区里非常常见、但并非唯一的组件变体组织方式。
- 不要把 `tailwind-merge` 理解成“可有可无的小优化”。只要组件允许外部传 `className` 覆盖，它通常就是稳定性的基础设施。
- 不要把“用了 builder”理解成“从此不需要评审类名”。builder 只是在集中表达变体，不会自动替你建立设计约束。

## tailwind-merge：去重与边界

- 可以把它理解成一个“Tailwind 类名裁判”。
- 它会根据 Tailwind 的冲突规则，决定哪些类应该保留、哪些类应该被删掉。
- 这样你才能真正做到“调用方最后传入的意图生效”，而不是把结果交给 Tailwind 内部排序碰运气。
- 最常见的用法就是封装 `cn = twMerge(clsx(...))`，然后把它作为所有 class 拼接的统一入口。

### 为什么它是「基石」

- 组件库必须开放 `className` 让消费者定制，如果没有 merge，任何「兜底样式」都可能被调用方的冲突类覆盖，且覆盖关系取决于 Tailwind 内部排序而非调用方意图。
- shadcn/ui 的所有组件都通过 `cn` 暴露覆盖点，`tailwind-merge` 才能保证「库默认 + 用户覆盖」是可预期的；不然需要禁止调用方使用部分类名或写大量 `!important`。
- 对 tokens 自定义（例如新增 `radius-4xl` 或品牌色）时，`tailwind-merge` 也能根据扩展配置正确识别冲突，避免出现「自定义类永远不会覆盖掉默认类」的问题。
- 作用：`p-4 p-2` → `p-2`；自定义 tokens/尺寸时需同步规则。
- 建议：在所有 class 拼接入口统一用 `cn`；对常见自定义（色板、spacing、radius）写额外 merge config 并加用例验证。
- 快测：在 Demo 按钮里故意写 `p-4 p-2`，观察输出；对自定义色板 class 也做覆盖测试。

如果你在手机上只扫一眼，这一节的核心其实就是一句话：没有 `tailwind-merge`，组件开放 `className` 往往就不够可靠。

### 没有 tailwind-merge 时

```tsx

function Button({ size = 'md', className, ...props }) {
  // 难以保证调用方不会传入冲突类（如 px-2），只能靠约定
  const base = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium'
  const sizeClass = size === 'lg' ? 'px-4 py-2.5 text-base' : 'px-3 py-2 text-sm'
  return <button className={clsx(base, sizeClass, className)} {...props} />
}

// 使用方
// 这里传了 px-2，最终输出 class 顺序取决于 props 位置，样式不可控
;<Button className="px-2 text-red-600" />
```

#### 示例：生成产物的「顺序陷阱」

Tailwind 会按内部规则排序候选（如 `p-0 → p-1 → p-2 → p-4 ...`），与 class 字符串的顺序无关：

```html
<!-- 期待 p-2 覆盖 p-4，但生成的 CSS 顺序仍是 p-2 在前、p-4 在后 -->
<button class="p-4 p-2 bg-blue-500 bg-red-500">示例</button>
```

```css
/* Tailwind 生成的片段（节选） */
.p-2 { padding: 0.5rem; }
.p-4 { padding: 1rem; } /* 出现在后面，仍然生效，覆盖掉 p-2 */
.bg-blue-500 { background-color: #3b82f6; }
.bg-red-500 { background-color: #ef4444; } /* 同样覆盖蓝色 */
```

即便 class 写成「后者想覆盖前者」，最终仍由 Tailwind 的排序决定，无法满足「调用方最后一项赢」的诉求。

### 引入 tailwind-merge 之后

```tsx

const cn = (...inputs: clsx.ClassValue[]) => twMerge(clsx(...inputs))

function Button({ size = 'md', className, ...props }) {
  const base = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium'
  const sizeClass = size === 'lg' ? 'px-4 py-2.5 text-base' : 'px-3 py-2 text-sm'
  return <button className={cn(base, sizeClass, className)} {...props} />
}

// 使用方
// 即便传入 px-2，tailwind-merge 也会保留「最后的有效值」，变为 px-2，行为可预测
;<Button className="px-2 text-red-600" />
```

#### 示例：merge 后的产物

```html
<button class="p-2 bg-red-500">示例</button>
```

```css
.p-2 { padding: 0.5rem; }
.bg-red-500 { background-color: #ef4444; }
```

通过删除冲突类，最终产物只包含用户期望的「最后一份声明」，不再受 Tailwind 内部排序影响。

### shadcn 风格组件的常见模式

```tsx
// utils/cn.ts

export const cn = (...inputs: ClassValue[]) => twMerge(clsx(...inputs))

// components/button.tsx
const base = 'inline-flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium'
const tones = {
  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
  ghost: 'bg-transparent text-foreground hover:bg-accent',
}
const sizes = { sm: 'h-8 px-2.5', md: 'h-10 px-3', lg: 'h-12 px-4 text-base' }

export function Button({ tone = 'default', size = 'md', className, ...props }) {
  return (
    <button
      className={cn(base, tones[tone], sizes[size], className)}
      {...props}
    />
  )
}

// 使用方：随意传入自定义类，默认与覆盖可预测
;<Button tone="ghost" className="px-10 bg-yellow-400 text-black" />
```

在上例中，调用方传入的 `px-10` 会去掉默认的 `px-3/px-4`，`bg-yellow-400` 也会覆盖默认的 `bg-primary`。`tailwind-merge` 让「库的默认 + 用户的覆盖」成为可靠的组合，避免写 `!important` 或约束文档里硬性禁止某些类名，从而成为这类可扩展组件模式的基石。

## cva：轻量变体工厂

```ts

export const badge = cva('inline-flex items-center rounded-md text-xs font-medium', {
  variants: {
    tone: {
      subtle: 'bg-muted text-muted-foreground border border-border',
      brand: 'bg-primary text-primary-foreground',
      danger: 'bg-destructive text-white',
    },
    size: { sm: 'px-2 py-1', md: 'px-2.5 py-1.5' },
  },
  compoundVariants: [{ tone: 'brand', size: 'md', class: 'shadow-sm' }],
  defaultVariants: { tone: 'subtle', size: 'md' },
})
```

- 场景：单槽组件（按钮、Badge、Input 等）；与 `cn` 组合解决冲突。

## tailwind-variants (tv)：内置 merge + slots

```ts

export const card = tv({
  base: 'rounded-2xl border bg-card/80 shadow-sm transition',
  slots: {
    header: 'flex items-center justify-between gap-2',
    body: 'space-y-2 text-sm text-muted-foreground',
    footer: 'flex items-center gap-2',
  },
  variants: {
    tone: { neutral: 'border-border', brand: 'border-primary/40 shadow-lg', subtle: 'border-muted bg-muted/60' },
    interactive: { true: 'hover:-translate-y-0.5 hover:shadow-md' },
  },
  defaultVariants: { tone: 'neutral', interactive: true },
})
```

- 场景：多槽组件（Card、Modal、List item），需要 slots/recipes 与自动 merge。

## cva vs tv 对照

| 项 | cva | tailwind-variants |
| --- | --- | --- |
| Merge | 无内置，需要 `cn` 包装 | 内置 tailwind-merge |
| 多槽 | 不支持 slots | 支持 slots/recipes |
| 心智负担 | 轻，语法简单 | 略重，类型更严格 |
| 适用 | 按钮/Badge 等单槽 | 卡片/模态/多槽组件，设计系统 |

不想记表格的话，可以直接记这条：

- `cva`：更轻，更适合按钮、徽标、输入框这类单槽组件。
- `tailwind-variants`：更完整，更适合卡片、弹窗、菜单这类多槽组件。

##  从设计到产物（示意图）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart LR
  Tokens["Design Tokens / @theme"] --> Variants["原子类 + variants"]
  Variants --> Builders["cva / tailwind-variants"]
  Builders --> Components["React/Vue 组件"]
  Components --> Content["content 精准扫描"]
  Content --> JIT["Tailwind JIT 生成按需 CSS"]
  JIT --> Merge["tailwind-merge 去重"]
  Merge --> Output["最终 CSS/HTML 产物"]
```

  
    
    Tokens：色板/间距/半径/排版等设计变量。
  
  
    
    Variants/Builders：用 cva/tv 封装 size、tone、state 等变体。
  
  
    
    Components/Content/JIT：组件消费 builder，content 精准扫描驱动 JIT 生成。
  
  
    
    Merge/Output：tailwind-merge 清理冲突，产出可预期的最终样式。
  

## 实用检查清单

- 所有动态 class 是否经 `cn`（含 `tailwind-merge`）合并？
- 是否存在散落的 `clsx`/字符串拼接 class？是否可迁移到 `cva`/`tv`？
- `variants/defaultVariants/compoundVariants` 是否集中在 builder 文件，业务组件不再拼装状态？
- 自定义 tokens 是否同步到 merge 规则？是否有用例验证覆盖顺序？

---

## PostCSS：插件化 CSS 引擎、历史地位与生态

<TailwindTopicHero topicId="tailwindcss/postcss" title="PostCSS：插件化 CSS 引擎、历史地位与生态" />

## 为什么关注 PostCSS

- 它是一个 AST 驱动的「二次加工」引擎，不是预处理器；你可以在标准 CSS 之上插入插件，完成兼容性、未来语法、定制输出等任务。
- Tailwind 本身就是 PostCSS 插件，`@tailwind`/`@apply`/`@layer` 等指令都通过 PostCSS 管线完成解析与生成。
- 生态稳固：`autoprefixer`、`postcss-preset-env`、`postcss-nesting`、`cssnano` 等插件几乎成为构建工具默认选项，间接推动 CSS 标准化。
- 平台适配能力强：通过插件可以批量完成 `px → rem/viewport`、RTL 翻转、主题 token 注入，也能在 Vite/webpack/Rollup/Parcel 之间平滑迁移。

## 核心机制（插件化 AST 管线）

- 输入标准 CSS → 解析为 AST（选择器、声明、规则） → 逐个插件修改树 → 输出 CSS/SourceMap。
- 插件是函数 `(root, result) => void`，可读取/修改 AST，并通过 `result.messages` 输出统计、警告或元数据（例如 Tailwind JIT 收集类名）。
- `postcss-load-config` 负责读取配置文件，`postcss-reporter` 可以把插件的提示汇总输出；`postcss-js` 允许用 JS 对象描述样式，方便测试。
- 顺序敏感：`@import`/模块化类插件应最先运行，语法转换/兼容性插件居中，Tailwind/设计系统类插件在语法转换之后，压缩（`cssnano`）放在最后。

## 历史节点与地位

- **2013-2014：Autoprefixer 诞生**，作者 Andrey Sitnik 把「给 CSS 自动加前缀」抽象成 AST 转换，PostCSS 因此成型。
- **2015-2016：插件生态爆发**：`postcss-nesting`、`postcss-custom-properties`、`postcss-modules`、`postcss-import` 等出现，webpack `postcss-loader` 成为标配。
- **2017-2019：成为「未来语法实验场」**：`postcss-preset-env` 将 CSS draft 特性以 Babel preset 式的体验提供给工程团队，CRA/Next.js 默认内置 PostCSS。
- **2020-至今：与 Tailwind/JIT 深度绑定**：Tailwind CLI/插件体系依赖 PostCSS；Vite、Parcel、Snowpack、Rollup 插件链均支持 PostCSS，生态趋向稳定与性能优化（并行、缓存）。

## 生态图谱（常用插件分层）

- **兼容性 / 未来语法**
  - `autoprefixer`：自动添加厂商前缀，解决兼容矩阵；仍是最广泛使用的 PostCSS 插件。
  - `postcss-preset-env`：类似 Babel preset，根据目标浏览器启用 polyfill（包含 `nesting`、`custom-media`、`custom-properties` 等）。
  - `postcss-nesting` / `postcss-nested`：提供与草案一致的嵌套；避免 Sass 风格的深层选择器。
  - `postcss-custom-media` / `postcss-media-minmax`：用别名或数学写法管理媒体查询。
- **模块化 / 工程化**
  - `postcss-import`：在 CSS 层面支持 `@import` 合并，配合 design tokens。
  - `postcss-modules`：把 CSS Modules 编译为哈希类名，暴露 JSON 映射，常与 React/Vue 组件并用。
  - `postcss-mixins`、`postcss-advanced-variables`：比 Sass 更轻量的 mixin/变量；适合渐进式迁移。
  - `stylelint`：虽然是独立工具，但使用 PostCSS 解析器实现规则检查。
- **优化与产物**
  - `cssnano`：分阶段压缩（合并声明、去重、压缩色值）；可按需求禁用破坏性规则。
  - `postcss-svgo`、`postcss-normalize`：对 SVG、normalize.css 等做针对性优化。
  - `postcss-rtlcss`、`postcss-px-to-viewport`：面向区域/设备的批处理（RTL、移动端视口）。
- **与框架/工具的绑定**
  - Tailwind/UnoCSS 核心插件依赖 PostCSS AST；`@apply` 与 `@layer` 均在 PostCSS 阶段展开。
  - Next.js、Vite、Nuxt、SvelteKit 默认内置 PostCSS 流水线；`astro` 也通过 `@astrojs/postcss` 集成。
  - CSS-in-JS 方案（Linaria、Vanilla Extract）在编译期同样复用 PostCSS 来处理静态样式与 autoprefixer。

## 与 CSS Modules / CSS-in-JS 的衔接

- **postcss-modules**：以插件形式实现 CSS Modules 规范，生成哈希类名与映射文件，是 [CSS Modules / Scoped 阶段](/docs/tailwindcss/history/css-modules) 的构建期实现之一；当你在 webpack/Vite 开启 `modules` 时，底层也是类似逻辑。
- **postcss-js**：允许用 JS 对象描述样式，再复用 PostCSS 插件链（如 autoprefixer/preset-env）；常被 CSS-in-JS 库用于在编译期/构建期对静态样式做兼容性处理，实现「CSS-in-JS 也能复用 PostCSS 生态」。
- **组合策略**：如果你在 React/Vue 里同时用 Tailwind + CSS Modules，可以把 `postcss-modules` 放在 import/nesting 之后、Tailwind 之前；若在 CSS-in-JS 中提取静态样式，则可用 `postcss-js` 让 autoprefixer/preset-env 同样生效。

## 对 CSS 的贡献与影响

- **加速草案落地**：在浏览器实现之前即可试用 nesting、自定义媒体、逻辑属性等，让标准化讨论有真实反馈样本。
- **统一兼容性故事**：Autoprefixer 让「不用背浏览器前缀」成为默认认知，减少了团队间的重复劳动与 Bug 密度。
- **生态基石**：构建工具把 CSS 解析/转换委托给 PostCSS，使得插件可复用、可组合，避免了各家重复造轮子。
- **教育与最佳实践输出**：诸如 `postcss-preset-env`、`cssnano` 的配置成为教材示例，帮助团队理解「顺序」「兼容矩阵」「安全转换」的重要性。

## 与其他方案的边界

- **对比 Sass/Less**：Sass 侧重语法糖（变量/嵌套/循环），PostCSS 更像插件平台，可同时提供未来语法与定制转换；二者可共存，但 PostCSS 更贴近标准语法。
- **对比 CSS-in-JS**：CSS-in-JS 在运行时/编译期生成样式，而 PostCSS 专注于构建期的静态转换；当样式可静态提取时，仍常使用 PostCSS 做兼容与压缩。
- **对比 Lightning CSS**：Lightning CSS 以 Rust 实现高性能的「一体化」CSS 处理器；PostCSS 胜在插件生态和可定制性，性能需求极高时可考虑混合使用（如仅替换压缩环节）。

## 典型配置与顺序示例

```js title="postcss.config.cjs"
module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-nesting'),
    require('tailwindcss'),
    require('postcss-preset-env')({
      stage: 1,
      features: { 'nesting-rules': false }, // 已用 postcss-nesting
      autoprefixer: { grid: true },
    }),
    require('cssnano')({
      preset: ['default', { discardComments: { removeAll: true } }],
    }),
  ],
}
```

- 导入/模块化放前面，保证后续插件看到完整的 AST。
- Tailwind（或其他设计系统插件）放在语法转换之后，保证接收标准化的规则。
- 压缩类插件放在末尾，避免提前折叠导致调试困难；生产与开发可拆分配置。

## 调试、性能与迁移建议

- **调试**：启用 `postcss-reporter`，在 CI 中收集各插件的 warning；配合 SourceMap 定位转换前后的规则。
- **性能**：减少插件数量，关注是否重复做同类转换（例如同时启用 `postcss-nesting` 与 preset-env 的 nesting）；在 Vite/webpack 中开启缓存或多线程。
- **迁移**：从 Sass/Less 迁移时，优先用 CSS 变量承载 tokens，再用 PostCSS 插件补齐缺失特性；若未来计划改用 Lightning CSS，可先保持插件最小集（import、nesting、autoprefixer）。
- **落地策略**：把 PostCSS 当作「基础层」，与 Tailwind、CSS Modules、甚至 CSS-in-JS 共存；在 monorepo 中复用一份 `postcss.config`，降低多包维护成本。

---

## shadcn/ui 的出现与意义

<TailwindTopicHero topicId="tailwindcss/shadcn-ui" title="shadcn/ui 的出现与意义" />

## 背景：复制源码，而非安装依赖

- 模式：shadcn/ui 不发布 npm 包，而是提供可复制的源码和 CLI，生成组件文件后由团队自行维护、改造。
- 影响：避免被包版本锁定，组件完全归团队所有；更新节奏、Breaking 变更都变成「你自己合并」，风险可控。
- 底座：Radix UI（无样式、可访问性交互） + Tailwind（视觉）+ `tailwind-merge`（冲突解析）+ `cva`/`variants`（变体），形成清晰的组合范式。

## 核心范式

1) 设计 tokens：通过 Tailwind 主题或 CSS 变量定义颜色、半径、间距。  
2) 变体声明：用 `cva` 或 `tailwind-variants` 管理 `size/tone/state` 等。  
3) merge 兜底：封装 `cn = twMerge(clsx(...))`，所有组件 `className` 都经由 merge。  
4) 可复制：CLI 产出 `Button.tsx` 等源码，直接落在仓库，便于二次定制和代码审查。

## 与其他 Headless UI 的结合

- Radix 不是唯一选项，同样模式可套到 Headless UI、Ark UI、Ariakit、React Aria/Headless、TanStack 状态机等无样式基座上。
- 关键在于：交互/可访问性由基座提供，视觉与变体由 Tailwind + `tailwind-merge` + `cva`/`variants` 接管。换基座时，仅需调整属性映射与状态类名。
- 示例：将 Ark UI 的 `Popover` 包装为 `cn + variants`，或用 Ariakit 的 Dialog 组件配合自定义 tokens，依然保持「复制源码、可改造、可覆盖」的模式。

## 什么是 Headless UI？常见基座与定位

- 定义：只提供交互逻辑与可访问性，不附带样式（或极少样式）的组件/Hook；通过 render props、slots 或原生元素组合让你自行决定 DOM 结构与 class。
- 典型代表：
  - Radix UI：无样式交互原件，搭配任意样式层。
  - Headless UI（Tailwind Labs）：提供 render props/slots 的交互组件。
  - Ark UI / Kobalte / Ariakit：无样式 + 可访问性，适合自定义主题。
  - React Aria / React Stately：Hook 形式提供交互与状态。
  - TanStack Table：表格/数据表逻辑完全 headless，可与任意样式库组合。
  - TanStack Form（原 React Form）：表单状态/校验 Hook，不负责视觉。
- 不算严格 headless 的场景：带默认主题/样式的 UI kits（如部分 reka UI 套件）通常已经封装视觉层，虽可定制但不属于纯 headless 范畴。

## Headless UI 库划分（速查）

- 交互原件型（组件 primitives）：Radix UI、Headless UI、Ark UI、Ariakit、Kobalte —— 提供 DOM 结构/状态机/可访问性，样式全由你决定。
- Hook/逻辑型：React Aria + React Stately（ARIA + 状态）、TanStack Form（表单状态），只暴露 Hook，不负责 DOM。
- 数据逻辑型：TanStack Table（表格/数据表逻辑，渲染自定义），近似纯逻辑层。
- 半 Headless/带样式的 kits：如部分 reka UI 或带主题的 UI 套件，提供默认皮肤但可替换，严格意义上不算纯 headless。

## 组件示例（缩写版）

```tsx
// utils/cn.ts

export const cn = (...inputs: ClassValue[]) => twMerge(clsx(...inputs))

// components/button.tsx

const button = cva(
  'inline-flex items-center gap-2 rounded-md font-medium transition-colors',
  {
    variants: {
      tone: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        ghost: 'bg-transparent text-foreground hover:bg-accent',
      },
      size: { sm: 'h-8 px-2.5 text-sm', md: 'h-10 px-3 text-sm', lg: 'h-12 px-4 text-base' },
    },
    defaultVariants: { tone: 'default', size: 'md' },
  }
)

type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof button>

export function Button({ tone, size, className, ...props }: ButtonProps) {
  return <button className={cn(button({ tone, size }), className)} {...props} />
}
```

- 通过 `cva` 统一管理 `tone/size`，`cn` 确保用户传入的类（如 `px-10`、`bg-yellow-400`）能可预测地覆盖默认值。
- 组件文件在项目内，可随团队规范调整（如换色板、改 radius、增加 slots），而不是等待上游发版。

## 行业意义

- **模板化脚手架**：为 Tailwind 场景提供「可复制源码 + merge + variants」的即插架构，成为大量团队的默认起点。
- **所有权转移**：将组件所有权从包作者转回使用团队，降低依赖风险，方便安全审计与定制化。
- **事实标准**：使 `tailwind-merge` 成为类名冲突解决的默认方案，催生各类 `cn` 封装与自定义 merge 规则。
- **无样式交互的普及**：推广了「Radix 等无样式交互 + 原子化样式」的组合，证明无需高度封装也能快速产出高可用组件。
---

> 想要深挖「merge 解决什么问题」？见「[tailwind-merge、cva、tailwind-variants 精要](./merge-and-variants)」章节。

---

## 样式隔离方案与原理

<TailwindTopicHero topicId="tailwindcss/style-isolation" title="样式隔离方案与原理" />

## 什么时候需要隔离

- 微前端/Widget/站外嵌入：宿主可能有全局 reset 或 UI 库，必须避免互相覆盖。
- 可发布组件库：希望类名可读但不污染全局，或交付「带样式的组件」给第三方。
- 多团队共用容器：同一页面叠加多套样式（营销区、业务区）时，需要给各自套壳。

> 大部分普通页面无需额外隔离；优先保证 tokens、variants、一致的 class 习惯即可。

## 方案速览

- 命名空间：`prefix` + `important`；选择器优先级隔离，最轻量但不改变层叠本质。
- 编译期哈希：CSS Modules/vanilla-extract；类名重写，天然不污染全局。
- 作用域容器：`data-*` + `:where` / `@scope`；为局部 DOM 套壳，提高特定区域优先级。
- Vue `scoped`：编译时给选择器自动加 `data-v-*`，局部生效。
- Shadow DOM / iframe：浏览器级边界；最强隔离，但需在边界内独立注入样式。
- preflight 控制：关闭/改写 base，避免 reset 污染宿主；常与以上方案组合。

## 命名空间（Tailwind prefix + important）

- **原理**：给所有生成类名加前缀（如 `tw-btn`），并通过 `important: '#app'` 或 `[data-scope=root]` 提升选择器优先级，减少宿主样式覆盖。
- **配置示例**：

```ts
// tailwind.config.ts
export default {
  prefix: 'tw-',
  important: '[data-scope=widget]', // 或 '#app'
  content: ['./src/**/*.{tsx,vue,html}'],
}
```

- **适用**：微前端、第三方嵌入、只需「不被覆盖」的场景。
- **注意**：仍是全局样式，宿主的 `!important` 仍可能干扰；preflight 仍会影响宿主（可关闭）。

## 编译期哈希（CSS Modules / vanilla-extract）

- **原理**：构建时把类名重写为哈希，JS 通过映射引用，默认不泄漏到全局；Tailwind 类可以在 `.module.css` 中用 `@apply` 复用。
- **示例（CSS Modules）**：

```css
/* card.module.css */
.card {
  @apply rounded-xl border bg-card/80 p-4;
}
```

```tsx

export function Card() {
  return 隔离的卡片
}
```

- **适用**：可发布组件库、中大型应用，希望「类名可读 + 不污染全局」。
- **注意**：跨组件复用 tokens 要单独导出变量；主题切换需额外变量管线。

## Vue `<style scoped>`

- **原理**：SFC 编译器为当前文件的元素和样式选择器都加上 `data-v-xxxx`，样式仅作用于本组件渲染出的 DOM。
- **示例**：

```html
<template>
  <section class="card">
    {{ title }}
  </section>
</template>

<style scoped>
.card {
  @apply rounded-xl border bg-card/80 p-4;
}
</style>
```

- **产物**：模板生成的节点带 `data-v-xxxx`，CSS 选择器编译为 `.card[data-v-xxxx]`。
- **适用**：Vue SFC 局部隔离，尤其是中小组件或局部定制。Tailwind 原子类可直接写在模板，也可在 scoped 样式里 `@apply`。
- **注意**：
  - 需要跨组件的全局样式用 `:global(.class)` 包裹；第三方组件需显式穿透（`::v-deep`）。
  - scoped 不重写类名本身，若要避免外部覆盖，可与 `prefix`/命名空间组合。

## 作用域容器（data-* + :where / @scope）

- **原理**：在根节点加标识，再用强选择器把样式限定在此容器内；`:where` 不增加特异性，便于覆盖；`@scope` 是未来方案（渐进支持）。
- **示例**：

```css
:where([data-scope=mini]) .card {
  @apply rounded-xl border bg-card/80 p-4;
}
```

```html
<section data-scope="mini">
  局部作用域
</section>
```

- **适用**：在宿主页面局部注入样式，或需要多套区域并存。
- **注意**：仍共用同一张 CSS，需手动管理作用域选择器；与 `prefix`/哈希可组合。

## Shadow DOM / iframe

- **原理**：利用浏览器原生隔离边界，Shadow DOM/iframe 内的样式默认不影响外部。
- **实现要点**：
  - Shadow DOM：在 Web Component 内注入 Tailwind 产物（可内联 `<style>`）；注意构建时把 CSS 携带进入组件。
  - iframe：在子页面独立引入 Tailwind 产物；通信/事件需额外桥接。
- **适用**：强隔离要求的 Widget、广告位、跨团队微前端。
- **注意**：每个边界都需要单独注入样式，打包与运行时体积可能增加；预渲染/SSR 时需处理样式注入。

## preflight 控制（可选组合）

- **原理**：关闭或局部启用 Tailwind preflight，避免全局 reset 影响宿主。
- **做法**：
  - 在 `tailwind.config.ts` 配置 `corePlugins: { preflight: false }`，或仅在特定入口引入 `@tailwind base;`。
  - 在组件库中不引入 preflight，让宿主自行决定全局 reset。
- **适用**：可发布组件库、微前端、与现有 UI 库共存时。

## 选择建议

- 嵌入第三方页面：`prefix` + `important` 起步；若宿主样式复杂，再加作用域容器。
- 组件库：优先 CSS Modules/vanilla-extract（编译期哈希），可关闭 preflight。
- Widget/广告位/微前端：Shadow DOM 或 iframe 提供最强隔离，视体积和运行时成本选择。
- 需要渐进策略：先用命名空间和 preflight 控制，确认仍有冲突再升级到容器/Shadow DOM。

---

## Tailwind 设计理念

<TailwindTopicHero topicId="tailwindcss/tailwind-core" title="Tailwind 设计理念" />

## Tailwind 本质是什么

- 可以把 Tailwind 理解成一条“压缩再展开”的流水线。
- 它会把很多常见视觉决策映射成可复用的 utility classes，例如颜色、间距、圆角、字号等。
- 然后在组件层重新把这些原子类组织起来，长成 `Button`、`Badge`、`Card` 这样的可读接口。
- 所以 Tailwind 真正解决的，不只是“少写 CSS”，而是让样式约束、类名组合和组件封装更容易对齐。

### 先记住这一句话

> 在团队工程化里，Tailwind 最有价值的地方通常不是“少写 CSS”，而是更容易建立约束、复用和审阅机制。

### 这一页建议怎么读

- 如果你是第一次看 Tailwind，重点看“入口、中段、出口”这 3 个部分，先把整体链路建立起来。
- 如果你已经在项目里使用 Tailwind，重点看“出口：组件重新长出语义”，因为大多数可维护性问题都出在这里。

:::info 资料参考
- [Tailwind CSS: Utility-first](https://tailwindcss.com/docs/utility-first)
- [Tailwind CSS: Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files)
- [UnoCSS Guide](https://unocss.dev/guide/)
:::

**Demo（整体串联）**

```ts
// tailwind.config.ts
export default {
  content: ['./src/**/*.{tsx,jsx,html}'],
  theme: {
    extend: {
      colors: { brand: { 50: '#f1f5ff', 500: '#3b82f6' } },
      spacing: { 3.5: '0.875rem' },
      borderRadius: { pill: '999px' },
    },
  },
  plugins: [require('@tailwindcss/typography')],
}
```

```tsx
// src/components/Button.tsx

const button = tv({
  base: 'inline-flex items-center justify-center font-medium transition-colors',
  variants: {
    tone: {
      primary: 'bg-brand-500 text-white hover:bg-brand-500/90',
      ghost: 'bg-transparent text-brand-500 hover:bg-brand-50',
    },
    size: { md: 'h-10 px-4 rounded-pill', lg: 'h-11 px-5 rounded-pill text-base' },
  },
  defaultVariants: { tone: 'primary', size: 'md' },
})

export function Button({ tone, size, className, ...props }) {
  return <button {...props} className={button({ tone, size, class: className })} />
}
```

## 入口：设计语义的单一来源

- 在团队实践里，最好先把设计值收敛成 token，再写类名。这一步看起来慢，实际上是在给后面所有组件减负。
- class 里优先引用 token，而不是直接写裸值。这样换品牌、换主题、做暗色模式时，改的是一层映射，不是全项目搜字符串。
- 团队要重点约束的不是“有没有用 Tailwind”，而是“是不是每个人都在随手发明新值”。

换句话说，这里的“入口”更适合作为推荐工程实践来理解，而不是 Tailwind 唯一正确的使用方式。

> 说明：Tailwind 官方既支持通过 theme、design tokens 与自定义 utilities 建立约束，也保留 arbitrary values、自定义 CSS 等逃生口；这里给出的写法是偏团队工程化的推荐路径。

**Demo：token 定义**

```ts
// tailwind.config.ts 片段
export default {
  theme: {
    extend: {
      colors: {
        brand: { 50: 'var(--brand-50)', 500: 'var(--brand-500)' },
      },
      spacing: { 3.5: 'var(--space-3_5)' },
      borderRadius: { pill: 'var(--radius-pill)' },
    },
  },
}
```

```css
/* src/styles/theme.css */
:root {
  --brand-50: #eef2ff;
  --brand-500: #4f46e5;
  --space-3_5: 0.875rem;
  --radius-pill: 999px;
}
```

## 中段：Tailwind 的生成逻辑

这一层可以拆成两部分看：一部分是 Tailwind 怎样生成类，另一部分是团队怎样给这些类加边界。

### 生成机制

- **JIT + content**：Tailwind 只会生成它扫描到的类，所以 `content` 写得越准，最终 CSS 越干净。很多包体问题，不是 Tailwind 本身慢，而是扫描范围太宽或者动态类太随意。
- **`@layer`**：它决定了 `base / components / utilities` 的覆盖顺序。`@apply` 可以用，但更适合做稳定复用，不适合偷偷塞业务逻辑。
- **插件**：适合把你们已经稳定下来的设计规则翻译成类，不适合把临时需求塞成新的语法糖。

### 约束机制

- **Variants / 关系类**：`md:`、`hover:`、`group-`、`peer-`、`aria-`、`data-` 这些能力很强，但强能力最容易被滥用。关系链一深，可读性会迅速下降。
- **tokens 与命名边界**：类可以很灵活，但团队最好不要让每个组件都在发明新值。否则 JIT 很快，代码仍然会很乱。
- **组件工厂**：当同一组 class 被反复组合时，就应该开始考虑 `cva`、`tailwind-variants` 或你们自己的 recipe 层。

如果你发现项目里的 class 变得越来越长、越来越难改，通常不是因为原子化本身有问题，而是中段缺少边界。

## 常见误解

- 不要把这一页理解成“Tailwind 官方要求你必须先做 token，再写类名”。这是偏团队工程化的推荐路径，不是官方唯一正确答案。
- 不要把 `@apply`、plugins、variants、组件工厂混成同一层东西。前两者更偏生成机制，后两者更偏团队封装策略。
- 不要把 Tailwind 理解成“类越少越好”或“绝不能写自定义 CSS”。真正重要的是边界清晰，而不是形式纯度。

**Demo：content 精准 + 局部 @layer**

```ts
// tailwind.config.ts 片段
export default {
  content: ['./src/app/**/*.{tsx,jsx}', './src/pages/**/*.{tsx,jsx}'],
  plugins: [],
}
```

```css
/* src/styles/components.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .card {
    @apply rounded-xl border border-slate-200 bg-white shadow-sm;
  }
  .card-title {
    @apply text-lg font-semibold text-slate-900;
  }
}
```

```tsx
// src/app/Card.tsx
export function Card({ title, children }) {
  return (
    
      {title}
      {children}
    
  )
}
```

**Demo：关系类和状态类**

```tsx
// src/components/Nav.tsx
export function Nav() {
  return (
    <nav className="flex items-center gap-4">
      <button className="relative group px-3 py-2 text-sm font-medium text-slate-600 hover:text-slate-900">
        Home
        
      </button>
      <button className="px-3 py-2 text-sm text-slate-600 data-[active=true]:text-brand-600 data-[active=true]:font-semibold">
        Docs
      </button>
    </nav>
  )
}
```

**Demo：自定义插件扩展一个工具类**

```ts
// tailwind.config.ts 片段

export default {
  // ...
  plugins: [
    plugin(({ matchUtilities, theme }) => {
      matchUtilities(
        {
          'grid-auto-fill': (value) => ({
            gridTemplateColumns: `repeat(auto-fill, minmax(${value}, 1fr))`,
          }),
        },
        { values: theme('spacing') },
      )
    }),
  ],
}
```

```tsx
// 使用自定义工具类

  {/* 自动填充列，最小 12rem */}

```

## 出口：组件重新长出语义

- 这是最容易被忽略、但最决定可维护性的阶段。
- 原子类在模板里很好试验，但项目一旦变大，真正决定代码质量的，是你有没有把这些类重新组织成稳定组件接口。
- 推荐把尺寸、色板、状态、slot 这类变化集中到 `cva` 或 `tailwind-variants` 里，而不是让业务组件到处拼。
- 再配合 `tailwind-merge` 收尾，才能让“组件默认样式”和“调用方覆盖样式”同时成立，并且行为可预测。

可以把这一步理解成：前面把样式拆小了，到了这里必须再把它们重新装回“人能读懂”的结构。

### 什么时候说明你已经走偏了

- 一个按钮组件有十几个布尔参数，但没有集中变体定义。
- 业务组件里反复出现大段重复 class，只是改了 1 到 2 个值。
- 调用方一传 `className`，你就不确定最终到底会生效哪条样式。

**Demo：用 tailwind-variants 简化 variants**

```tsx
// src/components/Badge.tsx

const badge = tv({
  base: 'inline-flex items-center gap-1 rounded-full font-medium',
  variants: {
    tone: {
      success: 'bg-emerald-50 text-emerald-700 ring-1 ring-emerald-100',
      warning: 'bg-amber-50 text-amber-700 ring-1 ring-amber-100',
    },
    size: { sm: 'px-2 py-1 text-xs', md: 'px-3 py-1.5 text-sm' },
  },
  defaultVariants: { tone: 'success', size: 'sm' },
})

export function Badge({ tone, size, className, ...props }) {
  return 
}
```

> 延伸阅读：
> - [Tailwind vs UnoCSS 对比](./tailwind-vs-unocss)
> - [tailwind-merge、cva、tailwind-variants 精要](./merge-and-variants)

---

## Tailwind vs UnoCSS 对比

<TailwindTopicHero topicId="tailwindcss/tailwind-vs-unocss" title="Tailwind vs UnoCSS 对比" />

## 要点

- Tailwind 提供「开箱即用」的 preset、插件、`tailwind-merge`、IDE 支持和社区范式；UnoCSS 提供高度可定制的 rules/variants/preset，但 merge/提示需自养。
- 选择标准：是否要复用社区资产、是否有资源维护规则库、对运行时/编译速度的需求、是否需要极度自定义的类名语义。

## 决策表（精简版）

| 维度 | Tailwind | UnoCSS |
| --- | --- | --- |
| 生态/社区 | 官方插件 + 大量社区 preset/组件范式，`tailwind-merge` 成熟 | rule/variant 任意扩展，高度灵活；预设较少，需要自养 |
| 类型提示 | 官方 language-service，IDE 友好 | 依赖 preset/插件质量，需额外配置 |
| Merge 去重 | `tailwind-merge` 针对 Tailwind 语义完善 | 默认不做去重，需自写或引入规则 |
| 运行时/JIT | v4 JIT 稳定，RSC/SSR 产物成熟 | 即时模式极快，自定义自由；规则库越大越需维护 |
| 迁移/资产 | 现成组件库（shadcn/ui、reka-ui）、设计体系示例丰富 | 灵活性高，迁移成本取决于自建规则与团队习惯 |

## 什么时候选 Tailwind？

- 不想维护 merge/variant/IDE 提示规则，倾向「拿来即用」。
- 需要快速复用社区资产、Preset、组件库（shadcn/ui、reka-ui 等）。
- 关注 RSC/SSR 稳定性、插件完备度，或需要让外部协作者迅速上手。

## 什么时候选 UnoCSS？

- 希望完全自定义类名语义（甚至 DSL），或已有内部 preset 库。
- 产物/规则必须极度可控（小程序/低码等），团队可维护规则和 merge 逻辑。
- 需要极快的即时模式，能接受自行实现去重/类型提示。

## 集成/实践差异

- IDE：Tailwind 语言服务即插即用；Uno 需根据 preset 配置提示插件。
- Merge：Tailwind 配 `tailwind-merge`，遇自定义 tokens/尺寸需更新规则；Uno 默认不去重，需要自写或组合。
- content 扫描：两者都需精准 content，Tailwind v4 JIT 对 SSR/RSC 产物更成熟；Uno 自定义时也要防止通配放大产物。
- 插件链：Tailwind 官方 typography/forms/animate 等即用；Uno 插件生态较少但可自由拼接规则。

## 简易选择流程（文本版）

1) 是否要复用现成组件/范式？要 → Tailwind；无所谓 → 继续。
2) 是否有维护规则库的人力？没有 → Tailwind；有 → 继续。
3) 是否需要极短类名/DSL？需要 → UnoCSS；不需要 → Tailwind。
4) 是否首屏/产物极限压缩并可自管规则？是 → UnoCSS；否则 Tailwind。

## 常见坑与对策

- Tailwind：content 过宽、动态类膨胀 → 收紧扫描范围，使用 `cva/tv` 参数化；自定义 tokens 记得更新 `tailwind-merge` 规则。
- UnoCSS：规则/merge/提示需要自养 → 建 preset 仓库 + merge 规则；对 DSL 做 lint，避免团队分叉。
- 两者：关系类嵌套过深可读性差 → 约束 `group/peer/aria/data` 深度；保持 tokens 映射表。

---

## Tailwindcss 原子类维护指南


## 前言

很多开发者，看到 `Tailwindcss` 的写法，或者初步使用它的时候，第一感觉可能就是 `写是真的爽，维护火葬场`。

诚然，软件工程中没有银弹，原子化有原子化的问题，但这不意味着像 `Tailwindcss`/`Unocss` 这类工具背后的原子化 `CSS` 思想本身没有价值。

最起码，原子化 `CSS` 在一定程度上帮助我们解决了: 类的命名，复用，以及迁移的问题，甚至也能避免了一定程度上的样式污染。

但是这似乎也带来了代码冗余，可读性差的问题。所以接下来的内容就是来帮助大家更好的认识，和维护 `Tailwindcss` 原子类。

## 语义化 CSS

首先要声明的是，原子化 `CSS` 和内联 `CSS` 一点关系都没有！内联 `CSS` 的优先级更高，但是复用性，可维护性要差很多。

其次 原子化CSS 不是绝对意味着一个 `class` 对应着一条CSS声明(`Declaration`)，比如 `w-0` 对应 `width: 0px;`

但是 `line-clamp-2` (效果为文字超过2行显示 `...` ) 这类一个就对应多个`CSS` 声明:

```css
.line-clamp-2{
  overflow: hidden;
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
}
```

所以原子化 `CSS` 中的原子化三个字，实际上指代的是 `CSS` **语义上** 效果的原子化。

## 本质

就本质上而言，其实不论是 `Tailwindcss` 还是 `Unocss`，你都可以把它们想象成一个漏斗，它们从你编写的代码中，通过正则，匹配到符合规则的字符串，然后再生成对应的 `CSS`，就这么简单。

其中，`Tailwindcss` 大部分时候是作为 `postcss` 插件来使用的，它可以和众多 `postcss` 插件很好的配合起来使用。

而 `Tailwindcss` 中的 `@tailwind` 指令，本质上也就是把当前 `@tailwind` 所在文件所属的 `Tailwindcss` 上下文中的 `base`,`components`,`utilities` 这些 `layer` 依次展开罢了。

所以你在一个文件里这样写:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
/* 再写一遍 @tailwind 会导致重复展开，造成大量的代码冗余 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

是没有意义的行为。

但是假如你通过 `@config` 指令，给不同CSS文件指定 `tailwindcss` 配置文件，类似于:

```css
/* app.css 文件, 应用全局的 tailwind.config.js */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* prose.css 文件,应用当前文件下的 tailwind.prose.config.js */
@config "./tailwind.prose.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
```

那么，这种一个项目，多 `tailwindcss` 配置，多 `tailwindcss` 上下文的方式，将给你带来很大的自由性。

## 类名冗余问题

类名冗余可能是我们使用 `Tailwindcss` 中经常遇到的问题，比如下面这段 `HTML`:

```html

  
    <input placeholder="Email" class="w-full rounded-lg border border-gray-300 bg-white px-4 py-3 focus:outline-none focus:ring-2 focus:ring-gray-700 focus:ring-offset-2 focus:ring-offset-gray-100" />
    <label class="flex cursor-pointer items-center justify-between p-1">
      Accept terms of use
      
        <input type="checkbox" class="peer h-6 w-12 cursor-pointer appearance-none rounded-full border border-gray-300 bg-white checked:border-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-900 focus-visible:ring-offset-2" />
        
      
    </label>
    <label class="flex cursor-pointer items-center justify-between p-1">
      Submit to newsletter
      
        <input type="checkbox" class="peer h-6 w-12 cursor-pointer appearance-none rounded-full border border-gray-300 bg-white checked:border-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-900 focus-visible:ring-offset-2" />
        
      
    </label>
    <button class="inline-block cursor-pointer rounded-md bg-gray-700 px-4 py-3.5 text-center text-sm font-semibold uppercase text-white transition duration-200 ease-in-out hover:bg-gray-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-700 focus-visible:ring-offset-2 active:scale-95">Save</button>
  

```

这段代码看着看着就晕了，虽然你可以通过 `class` 很直观的了解到了每个元素的样式，但是数量一多，理解成本还是会指数级上升的。

为了缓解这个问题，`Windicss` / `Unocss` 还设计了 [Attributify 模式](https://unocss.dev/presets/attributify#attributify-mode)，使得它们可以依据属性进行分组归类，使得原子化类显得非常直观:

```html
<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>
```

而且 `Unocss` 还利用它能够在编译时，改变用户代码的能力，构建了许多转化语法糖，比如 `transformer-variant-group`:

```html

```

这些在一定程度上，都能缓解类名冗余的问题，但是无法解决这个问题。

那么，在 `Tailwindcss` 遇到这样的问题，应该如何处理呢？

## 最简单方式: `@apply` 提取

[`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply) 是 `Tailwindcss` 里的一个 `CSS` 指令，它可以把多个原子类给合并到一个你自定义的 `CSS` 节点中。

而且，写法上它也遵从 `HTML` 里的写法。你可以很容易的从 `HTML` 中复制你的原子类到 `CSS` 中，再把它们提取成一个单独的类。

```css
@layer components {
  /* 使用 utilities 里的 inline-flex-center */
  .btn {
    @apply inline-flex-center font-bold py-2 px-4 rounded cursor-pointer;
  }
  /* 使用 components 里的 btn */
  .btn-pink {
    @apply btn bg-pink-600 hover:bg-pink-900 text-white;
  }
}

@layer utilities {
  .inline-flex-center {
    @apply inline-flex items-center justify-center;
  }
}
```

效果如下所示:

<button class="btn">btn</button>
<button class="btn-pink">btn-pink</button>

这样，通过提取和组合，我们可以对原子类进行更高程度上的封装，值得一提的是 `Tailwindcss` 中最流行的 UI 框架: `daisyUI` 原理上也是类似的，不过它进行了进一步的处理和预提取，并最终把它们封装成了一个 `Tailwindcss` 插件罢了。

最终，我们把大量的原子化类，进行提取组合，并最终提炼出了原子化的CSS组件 `card`,`label`,`btn`,`input`组件，那么上面的 `HTML` 就被改造成了:

```html

  
    <input placeholder="Email" class="input input-bordered" />
    <label class="label cursor-pointer">
      Accept terms of use
      <input type="checkbox" class="toggle" />
    </label>
    <label class="label cursor-pointer">
      Submit to newsletter
      <input type="checkbox" class="toggle" />
    </label>
    <button class="btn btn-neutral">Save</button>
  

```

此为最简单，最直接的方式去减小类名的冗余程度，但是这种方式也存在一定的缺陷。比如 `@apply` 这种本质上还是基于 `CSS AST` 的，用得多会有性能问题，另外智能提示也不友好。

所以刚开始可以这样使用，到出现性能问题的时候，我们就需要进行更高一部分的封装: 提炼成 Tailwindcss 插件

## 提炼成 Tailwindcss 插件

`Tailwindcss` 官方文档实际上希望我们把样式，提炼成 [Tailwindcss Plugin](https://tailwindcss.com/docs/plugins)

这样做有许多的好处，比如智能提示友好，性能也比 `@apply` 要高。

它的编写方式也非常简单:

```js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto',
        },
        '.content-hidden': {
          'content-visibility': 'hidden',
        },
        '.content-visible': {
          'content-visibility': 'visible',
        },
      })
    }),
  ]
}
```

其中 `addUtilities`/`addComponents`/`matchUtilities`/`matchComponents` 这些函数都是用来添加对应的样式到 `tailwindcss` 中。

它们参数中，添加的 `CSS` 对象遵从 [`CSS-in-JS 语法`](https://tailwindcss.com/docs/plugins#css-in-js-syntax)。

幸运的是，我们无需重新编写代码，便可以直接把之前 `@apply` 部分的代码，转化成 `CSS-in-JS` 对象。这一切都只需要我们用到 [`postcss-js`](https://github.com/postcss/postcss-js) 这个工具。

[`postcss-js`](https://github.com/postcss/postcss-js) 作为 `postcss` 生态的组成部分，它能够解析 `CSS-in-JS` 对象，同样它也能够把 `postcss` 解析的 `AST` 转化成 `CSS-in-JS` 对象。

所以它自然可以把 `CSS` 字符串，直接转化成 `CSS-in-JS` 对象。这正是我们想要达到的效果。大体的执行脚本如下:

```js
const postcss = require('postcss')
const path = require('path')
const fs = require('fs')
const tailwindcss = require('tailwindcss')
const postcssJs = require('postcss-js')

async function main () {
  const { root } = await postcss([
    tailwindcss()
  ]).process('@tailwind components;' + `@layer components{
    .btn{
      @apply inline-block cursor-pointer rounded-md bg-gray-700 px-4 py-3.5 text-center text-sm font-semibold uppercase text-white transition duration-200 ease-in-out  focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-95;
    }
    /* more... */
  }`,
    {
      from: undefined
    })
  fs.writeFileSync(path.resolve(__dirname, './output.json'), JSON.stringify(postcssJs.objectify(root)), 'utf8')
}

main()
```

对应的 `tailwind.config.js` 添加 `raw` 来提取 `btn` 类。

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [{
    raw: 'btn'
  }],
}

```

当然这是保存到本地磁盘的方式，接着我们编写的 `Tailwindcss Plugin` 只需要去引用这样的对象，把它们作为参数添加到 `addUtilities`/`addComponents` 中，即可正常使用。

例如这样的生成结果为:

```json
{
  ".btn": {
    "display": "inline-block",
    "cursor": "pointer",
    "borderRadius": "0.375rem",
    "--tw-bg-opacity": "1",
    "backgroundColor": "rgb(55 65 81 / var(--tw-bg-opacity))",
    "paddingLeft": "1rem",
    "paddingRight": "1rem",
    "paddingTop": "0.875rem",
    "paddingBottom": "0.875rem",
    "textAlign": "center",
    "fontSize": "0.875rem",
    "lineHeight": "1.25rem",
    "fontWeight": 600,
    "textTransform": "uppercase",
    "--tw-text-opacity": "1",
    "color": "rgb(255 255 255 / var(--tw-text-opacity))",
    "transitionProperty": "color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter",
    "transitionDuration": "200ms",
    "transitionTimingFunction": "cubic-bezier(0.4, 0, 0.2, 1)"
  },
  ".btn:focus-visible": {
    "outline": "2px solid transparent",
    "outlineOffset": "2px",
    "--tw-ring-offset-shadow": "var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color)",
    "--tw-ring-shadow": "var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)",
    "boxShadow": "var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000)",
    "--tw-ring-offset-width": "2px"
  },
  ".btn:active": {
    "--tw-scale-x": ".95",
    "--tw-scale-y": ".95",
    "transform": "translate(var(--tw-translate-x), var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))"
  }
}
```

不过这种方式其实也完全可以更进一步，接下来进入下一个章节: `postcss` 预生成产物。

## postcss 预生成产物

其实在上一章中，我们已经使用到了一些预先生成的思想了。

毕竟 `tailwindcss` 本身不过是个 `postcss` 插件，我们自然可以通过编写脚本的方式，预先的把 `CSS` 先生成出来，直接交给项目进行使用的。

比如我们要从 `utilities` 提炼出一些 `flex` 相关的工具类出来，那么我们就可以写一段脚本:

```js
const path = require('path')
const fs = require('fs')
const postcss = require('postcss')
const tailwindcss = require('tailwindcss')

async function main () {
  const { css } = await postcss([
    tailwindcss()
  ]).process('@tailwind utilities',
    {
      from: undefined
    })
  fs.writeFileSync(path.resolve(__dirname, './output.css'), css, 'utf8')
}

main()
```

对应的 `tailwind.config.js` 配置:

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [{
    raw: 'flex flex-1 flex-none flex-auto flex-initial'
  }],
}
```

生成的 `output.css` 产物

```css
.flex {
    display: flex
}
.flex-1 {
    flex: 1 1 0%
}
.flex-auto {
    flex: 1 1 auto
}
.flex-initial {
    flex: 0 1 auto
}
.flex-none {
    flex: none
}
```

所以按照这种方式，我们也可以把之前那些 `@apply` 直接复制过来，进行处理，生成出 `CSS`，交给项目来进行使用。同样也能通过这种方式来提炼出 `CSS` 组件。或者把插件里面的 `CSS` 代码，比如 `daisyUI` 里面的样式给 “倒出来”。

## `Unocss` 对比 `Tailwindcss`

`Unocss` 相比 `Tailwindcss` 强大之处，在于 `Tailwindcss` 仅仅只是一个 `postcss` 插件，而 `Unocss` 不是。

`Tailwindcss` 功能简单到，它只是从我们的源代码 `(content)` 中，提取到字符串，然后去生成 `CSS` 节点。

而 `Unocss` 更多时候作为一个打包插件去使用，它可以复用我们打包的产物，并从里面进行提取字符生成 `CSS` 节点，甚至它有能力去修改我们的代码 `(transformer)`。这样的能力 `Tailwindcss` 是不具备的，这也是 `Unocss` 快且功能丰富的原因。

不过单纯这样比较是没有意义的，就像名义上 `Unocss` 快是因为它不用解析 `AST`，但是你一旦想用到 `@apply` 这样的 `directives` 功能，`Unocss` 也不可避免的去使用 `css-tree` 去解析和操纵 `AST`。而这个功能是作为 `postcss` 插件的 `Tailwindcss` 内置的，而 `Unocss` 需要额外的包去实现。

所以比较公平的比较方式，应该是用 `Unocss` 的 `postcss` 插件来和 `Tailwindcss` 做比较。

不过，作为 `Windi CSS` 思路继承者的 `UnoCSS`，在原子化 `CSS` 各个方面都做的更加极致也是不争的事实。而且由于作者 `antfu` 在国内国外的高人气，也吸引了许多志同道合的开发者，积极的为 `UnoCSS` 做贡献，使得生态也生机勃勃，未来可期，真是羡煞旁人啊!

而 `Tailwindcss` 作为一个成功商业化的开源产品，虽然不如 `UnoCSS` 激进，但出的比较早，相对来说生态更丰富，使用人数更多一些，相对应的前人踩过的坑，解决方案也完备一些，而且有公司和资金支持，理论上不会烂尾。

所以希望 `Unocss` 多为我们探索更多原子化的极限，也希望 `Tailwindcss` 多争点气，虚心多学习学习别人的优势。

## More

更多的方法论 Coming Soon...

---

## 旧有uni-app项目升级webpack5指南


:::caution
目前 `uni-app` 默认创建的 `vue2` 项目,已经全面使用 `@vue/cli-service@5` 了(2023-10)，所以目前正常升级即可，本指南废弃! 留作归档处理

仓库中的 classic `uni-app vue2/webpack` demo 也已经移除。使用 `uni-app vite vue3` 的开发者可以忽略此指南。
:::

由于目前 `uni-app` `hbuilderx`和`cli`默认创建的 `vue2` 项目，还是使用的 `@vue/cli-service@4`

为了使用更先进更有生产力的 `webpack5` 和 `postcss8` 我们必须要升级到 `@vue/cli-service@5`

那么旧有的老项目应该如何升级呢？

### 1. 升级 `@dcloudio/*` 相关的包

在项目根目录，执行:

```bash npm2yarn
npx @dcloudio/uvm alpha
```

然后选择 `y` 后，出现提示，选择你项目使用的包管理器，运行即可。

此时你所有的 `@dcloudio/*` 相关的包，被升级到了 `2.0.2-alpha-xxxxxxxxxxxx` 的版本。

### 2. 升级 `@vue/cli-*` 相关的包

使用你的包管理器，升级 `@vue/*`,`@vue/cli-*` 相关的包到 `5.x` 版本。

```json
{
  "@vue/babel-preset-app": "^5.0.8",
  "@vue/cli-plugin-babel": "~5.0.8",
  "@vue/cli-plugin-typescript": "5.0.8",
  "@vue/cli-service": "~5.0.8",
}
```

### 3. 升级你所有的 `webpack` `plugin` 和 `loader`

由于你使用了最新版本的 `webpack` 你可以把那些相关的包，升级到最新的版本，

比如 `sass-loader`, `copy-webpack-plugin` 等等

而且由于你使用了 `5.x` 版本的 `@vue/cli`，里面默认依赖了 `postcss8`

所以你也按需应该升级一下你所依赖的 `postcss` 插件版本。

### 4. 配置文件升级

比如 `babel.config.js`、`postcss.config.js` 这类配置文件，都需要按你当前项目实际依赖链路同步升级。

诸如这种类似的，都可以新创建一个的 `uni-app alpha` 的项目，然后把里面的配置直接复制过来，再改改 `postcss.config.js` 把 `tailwindcss` 注册进去即可。

### 5. 运行排错

接下来就是，删掉你的 `lock` 文件，重新安装所有包，并运行你的项目！

当然运行时，很有可能报各种各样的错误: 比如 `babel-xxx` 插件找不到，这种安装即可。

或者什么 `webpack` 插件报错，这种可以暂时去除看看能不能打包成功。

:::tip
假如你使用了 `uni-app` 的同时使用了云函数，云函数导致编译到微信出现 `TypeError: I18n is not a constructor`

解决方案详情见: <https://ask.dcloud.net.cn/question/170057>

相关 issue : [issues/74#issuecomment-1573033475](https://github.com/sonofmagic/weapp-tailwindcss/issues/74#issuecomment-1573033475)
:::

---

## 重新思考 weapp-tailwindcss 的未来


大家好，我是 [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss)、[weapp-vite](https://github.com/weapp-vite/weapp-vite) 的作者 icebreaker。

最近我一直在思考 `weapp-tailwindcss` 的未来，以至于都没有怎么玩，最近回归的星际争霸2。

## 巨大的阻碍

为什么？因为之前有一个很重要的问题，严重阻碍了 `weapp-tailwindcss` 发展的脚步。

那就是 `tailwind-merge` / `class-variance-authority` / `tailwind-variants` 这些极其重要的原子化样式基础包，没有什么很好的办法在小程序里使用。

### 为什么无法在小程序里使用？

简短一点来说，核心原因是，小程序 `wxml` 类名中，不允许很多特殊字符串，比如 `!`、`[`、`]`、`#` 等字符。

所以 `weapp-tailwindcss` 根据这个设计，在**编译时**，就对 `tailwindcss` 类名进行转换，从而达到了兼容市面上众多小程序的编译插件。

比如用户写的是 `bg-[#123456]`，被 `weapp-tailwindcss` 捕获到了之后，在**编译**的时候，就会同时把 `wxml`、`js`、`wxss` 里面的这个类名转换成小程序可以接受的 `bg-_h123456_`。

而 `tailwind-merge` 它们都是在**运行时**进行计算的，那时候它们接收到的，已经是 `bg-_h123456_` 这种转译之后的字符串，自然合并不了，导致到处出错。

为了兼容，我做了非常多的尝试！给大家展示一下我的受苦之路吧！

## 1. tailwind-merge plugin / createTailwindMerge

最直观的念头，就是给 `tailwind-merge` 写一个 `weapp-tailwindcss` 专用插件就好了!

于是我开始阅读 `tailwind-merge` 源代码，并尝试使用 `extendTailwindMerge` 和 `createTailwindMerge` 完全创建出一个属于我自己的 `weapp-tailwind-merge` 来。

在尝试过程中，我把 `tailwind-merge` 的内部冲突表导出，尝试用自定义 `escape hook` 覆盖那些非法字符；甚至写了一个半成品的 `createTailwindMerge` 变体，希望能在编译阶段就生成完全符合小程序命名规则的类名。

然而，现实很快给了我当头棒喝：`tailwind-merge` 对**运行时**字符串的依赖极强，部分字符是强依赖，根本无法替换。

下面这几个字符串都是写在常量里的，无法通过配置更换

```ts
export const IMPORTANT_MODIFIER = '!' // 小程序不行
const MODIFIER_SEPARATOR = ':' // 小程序不行
```

详见 https://github.com/dcastil/tailwind-merge/blob/v3.3.1/src/lib/parse-class-name.ts。

所以这已经不是 `extendTailwindMerge` 和 `createTailwindMerge` 能够解决的问题了。

摆在我面前的，是一条看不到未来的路：为了强行兼容，我需要重写它的核心，fork 一个全新的包，这个成本是巨大的。

## 2. 编译期豁免

第二条路看起来更务实：沿用我熟悉的编译期管线，给 `twMerge` / `twJoin` / `cva` 等函数做“豁免处理”。

我当时是这样想的，只要在**编译时**忽略它们内部的转义，**运行时**拿到的就是完整的 class 字符串，那 tailwind-merge 不就能工作了吗？

然后我再包装一下 `twMerge` 函数，让它获取最后的结果的时候 escape 不就行了吗？

大概长这样：

```ts
export function cn(...inputs: ClassValue[]) {
  const result = twMerge(inputs)
  return escape(result)
}
```

然后我让 `cn` 里面的字面量和模板字符串跳过转义不就行了吗？

```ts
// 第一个是字符串，第二个是模板字符串，它们对应的 ast 类型不同，需要分开处理
// 里面的不转译
cn('bg-[#123456]',`bg-[#987654]`)

// 假如转译那么，结果如下
// cn('bg-_h123456_',`bg-_h987654_`)
```

看上去运行良好，然而情况正在变得越来越复杂：

嘿，变量引用来了：

```ts
const a = 'bg-[#123456]';
cn(a,"xx","yy")
```

嘿嘿，变量引用 + 表达式来了：

```ts
const a = 'bg-[#123456]' + ' bb' + ` text-[#123456]`;
cn(a,"xx","yy")
```

嘿嘿嘿，变量引用链路 + 表达式 + 模板插值来了：

```ts
const b = 'after:xx';const a = 'bg-[#123456]' + ' bb' + `${b} text-[#123456]`;
cn(a,"xx","yy")
```

哈哈，只是在考验我操作 ast 进行预编译的水平而已！

吃我一拳：`ASTNodePathWalker` + `scope.getBinding` + `WeakMap`，哈哈轻松消灭！

于是我以为这条思路可行，编写了 `@weapp-tailwindcss/merge` 的 v1 版本。

直到用户提交了新的 case！

### 新的挑战

什么，怎么还有你们这种相互引用的情况！

```js
// shared2.js
export const ddd = 'bg-[#123456]';

const a = 'bg-[#123456]';

export {
  a as default
}
```

```js
// shared.js
export const a = 'bg-[#123456]';

const b = 'bg-[#123456]';

const c = 'bg-[#123456]';

const d = 'bg-[#123456]';

export default d

export {
  b
}

export {
  c as xaxaxaxa,
}

export * from './shared2'
```

```js
// main.js

cn(bb, cc, aa, shared.default, shared.a, "[]", "()")
```

……我吐了，这是要我自己去实现一个 webpack / rollup 打包器嘛？有点搞不定啊！

不过困难怕什么，我要迎难而上！于是我仿照了 `rollup` 的思路，收集了每个模块的 `import` / `export` 这里面大量的 ast 节点，并构建出了一个 `ModuleGraph`。

另外表面上看这条路是可行的，我甚至找到了几个 `demo` 可以跑通，我还把豁免名单抽离出来，变成了 `ignoreCallExpressionIdentifiers` 配置项，以为自己解决了问题。

### 然而理想很丰满，现实很骨感

这套方案高度依赖 AST 解析和构建工具的配合，我写的插件无法保证**运行时**得到的类名永远完整。构建链路上的任一环节——Terser、esbuild、rollup 插件甚至手写 Babel 宏——都可能把函数名或模板字符串的标识符压缩重命名，导致最后留给**运行时**的是一个残缺的字符串。

用人话说就是 `cn` , `twMerge`, `tv` 这种方法，在产物里面被重命名成 `e`/`a`/`c` 这种玩意，所以我必须在压缩之前就进行豁免操作，但是那时候我似乎无法去准确收集产物的模块依赖情况(可能是水平不够导致的)。

那一刻我意识到，所谓“编译期豁免”只是在延迟爆炸时间，而不是解除危机。

在两条路都走到尽头之后，只剩下一个选择：彻底重构 merge，让逃逸逻辑回归**运行时**，让编译阶段恢复简单纯粹。

## 为什么要重写 merge？

复盘 1.x 旧版 merge，我发现我当时的设计基于两个假设：一是 `tailwind-merge` 的输入输出始终可控，二是编译器可以精准标记所有“需要放行”的调用。这两个假设已经被现实击碎。

早期的 `@weapp-tailwindcss/merge` 主要目标是“把 tailwind-merge 的结果变成小程序合法类名”。我采取的策略是：

- 继续使用 `tailwind-merge` 做冲突解析；
- 在编译阶段通过函数名黑名单 `ignoreCallExpressionIdentifiers` 跳过对 `twMerge` / `twJoin` / `cva` 等调用的转义；
- 把责任交给开发者：**运行时**得到的类名包含非法字符，需要手动再 escape。

这种模式在 Tailwind CSS v3 勉强能用，但一到 v4 就崩溃了：

1. **编译期豁免并不等于安全**  
   `twMerge('text-[#ececec]', 'text-(--my-custom-color)')` 最终仍然输出原始字符串。稍微复杂一点的条件拼接、链式调用、动态导入，编译器根本判断不出来该不该跳过。
2. **函数名黑名单无法覆盖新的 API**  
   新版本开始导出 `create()`、variants（`tv`）等工厂，调用形式千奇百怪，编译阶段根本匹配不到。
3. **任意值语法越来越灵活**  
   Tailwind v4 的任意值可以是 `text-[theme(my.scale.foo)]` 这种无法静态推断类型的写法。靠黑名单永远落后，反而让用户更困惑。

## 新版 merge 的核心思路

决定“把锅背回**运行时**”以后，我做的第一件事就是把入口全部进行统一：`twMerge` / `twJoin` / `createTailwindMerge` / `extendTailwindMerge` / `cva` / `variants`……统统绑进同一套 transformer 里。

思路很简单：先找出它们共有的“进场”和“退场”动作，再把逃逸拆成前后两个钩子， `escape` 和 `unescape`。

```ts
const transformers = resolveTransformers(options)

const aggregators = {
  escape: transformers.escape,
  unescape: transformers.unescape,
}
```

在实现里我刻意把 escape 和 unescape 拆成两个“齿轮”。不管是用户直接手点 `twMerge`，还是 variants 工厂兜一圈回来，都会先进统一的预处理，再丢给 tailwind-merge。

这等于在**运行时**补了一层“语义编译器”。

### 双向处理链

所以现在每次 merge 现在都得过一遍 `unescape -> tailwind-merge -> escape` 这样的流程：

```ts
 const normalized = transformers.unescape(clsx(...inputs))
 return transformers.escape(fn(normalized))
```

但是这样还不够，为了实现 `escape` 和 `unescape` 我还必须从源头上出发，更改 `@weapp-core/escape` 的转译规则，才能让每一个字符串映射变得独一无二

### 重写 @weapp-core/escape

老 escape 工具一直挂在 `@weapp-core/escape` 上，它走的是“多对一”映射，贴一段旧代码大家感受一下：

```ts
export const MappingChars2String: MappingStringDictionary = {
  '[': '_',
  ']': '_',
  // for tailwindcss v4
  '(': 'y',
  ')': 'y',
  '{': 'z',
  '}': 'z',
  '+': 'a',
  ',': 'b',
  ':': 'c',
  '.': 'd',
  '=': 'e',
  ';': 'f',
  '>': 'g',
  '#': 'h',
  '!': 'i',
  '@': 'j',
  '^': 'k',
  '<': 'l',
  '*': 'm',
  '&': 'n',
  '?': 'o',
  '%': 'p',
  '\'': 'q',
  '$': 'r',
  '/': 's',
  '~': 't',
  '|': 'u',
  '`': 'v',
  '\\': 'w',
  '"': 'x',
}
```

问题马上就来了：它完全做不到配对 `unescape`。`[` 和 `]` 被一起砸成 `_`，`(` / `)`、`{` / `}` 也全堆在同一个值上，**运行时**根本还原不回去。举个让人头疼的例子：`escape('[bg:red]') === '__bg_red_'`。

所以我直接把 `@weapp-core/escape` 推倒重练，写成一个可逆的“状态机”。每个非法字符都分到独一无二的逃逸片段，还带长度前缀，跑完 `unescape(escape(input))` 就一定回到原样。为了防止它在极端输入上翻车，我拉了十几组 property-based 测试，emoji、空格、重复 escape 全安排上写了大量的单元测试，确保往返都符合预期。

下面是当前版本的核心映射表，展示了我如何为每个非法字符分配唯一的 escape 片段，便于和旧版多对一的写法做对比：

```ts
export const MappingChars2String = {
  '[': '_b',
  ']': '_B',
  '(': '_p',
  ')': '_P',
  '#': '_h',
  '!': '_e',
  '/': '_f',
  '\\': '_r',
  '.': '_d',
  ':': '_c',
  '%': '_v',
  ',': '_m',
  '\'': '_a',
  '"': '_q',
  '*': '_x',
  '&': '_n',
  '@': '_t',
  '{': '_k',
  '}': '_K',
  '+': '_u',
  ';': '_j',
  '<': '_l',
  '~': '_w',
  '=': '_z',
  '>': '_g',
  '?': '_Q',
  '^': '_y',
  '`': '_i',
  '|': '_o',
  '$': '_s',
} as const
```

文章里我只放这份“简化表”，因为它才是**运行时**默认用的版本，开发者平时看到的也是它。更复杂的兼容映射我留在文档和测试里。

### **运行时**配置

新的 `create()` 可以随手关掉任意环节，这是和社区聊得最多的诉求。有团队想“开箱默认就好”，也有老项目背着一堆历史包袱，得慢慢迁移。所以我直接给了一排明确开关，想保守就保守，想激进就激进。

```ts
const { twMerge: passthrough } = create({ escape: false, unescape: false })
```

配合 SSR 或老数据兼容的时候，也不用再额外写工具函数：服务端直接把 escape 全关掉，只做 merge 校验；到小程序再开回完整逃逸步奏，迁移过程就能一步一步踩稳。

另外还开放了 `map` 字段，用于统一用自己的字符映射。

## 发布 4.7.x 版本

绕了这么多弯，所有成果最终都塞进了 `weapp-tailwindcss@4.7.x` 和 `@weapp-tailwindcss/merge@2.x` 中。算是 weapp-tailwindcss **运行时**时代的第一声号角。

欢迎大家把新版 `@weapp-tailwindcss/merge` 用到真实项目里，更欢迎在社区继续砸想法，我会把这些反馈当作下一轮迭代的燃料，让 Tailwind CSS 在小程序世界里始终“开箱即用”。

有时候我也在想，为小程序这个逐渐感觉不怎么活跃的生态，花了这么多时间，感觉有点不值。但是转念一想，起码在我这个领域我已经通过不断的学习，真的掌握了很多东西。

起码，对 Tailwind CSS 进行符合中国小程序技术特色的改造方面，我也算是第一人了吧。每每想到这，就感觉自己好像还稍微有这么一点点自豪呢，哈哈哈。

如果你也在思考工具链，编译，AST 等等方面的问题，希望这篇文章能给你一点启发。

## 源代码附录

- [tailwind-merge 插件文档](https://github.com/dcastil/tailwind-merge/blob/v3.3.1/docs/writing-plugins.md)
- [NodePathWalker](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/packages/weapp-tailwindcss/src/js/NodePathWalker.ts)
- [ModuleGraph](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/packages/weapp-tailwindcss/src/js/ModuleGraph.ts)

---

## 4.0.0 🚀

weapp-tailwindcss v4.0 正式发布，核心亮点是兼容 `tailwindcss@4` 并引入 `tailwind-merge` 运行时整合能力。文章总结了升级背后的思路，并提供 uni-app 示例帮助你快速落地。

<!-- truncate -->

![4.0 release](https://cdn.jsdelivr.net/gh/sonofmagic/static/mbpv4-release.png)

# weapp-tailwindcss v4.0 发布了！

## **总结**

经历了一番自虐式开发后，`weapp-tailwindcss` **v4.0** 终于发布了！

在清理了一些自己当初写的屎山代码后，我终于实现了心心念念的两个大功能：

1. **支持 `tailwindcss@4.x` 版本**
2. **支持 `tailwind-merge`**

> 因为 `tailwindcss@4` 直接变成了一个样式预处理器，定位上类似 `Sass` / `Less`，所以相关的改动还是挺大的。目前 `weapp-tailwindcss@4` 版本也同时兼容 `tailwindcss 4+3+2(jit)` 三个版本了。

想快速上手集成？欢迎访问 [weapp-tailwindcss 官网](https://tw.icebreaker.top/)！
如果你想进一步了解细节，下面有个示例，看看就懂了。

---

## **uni-app 快速集成示例**

这里我们以 **`uni-app`（Vue3 + Vite）** 为例。

### **1. 安装依赖**

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/vite weapp-tailwindcss
```

然后，把下面这段脚本加入 `package.json` 的 `scripts` 字段里：

```json title="package.json"
{
  "scripts": {
    // highlight-next-line
    "postinstall": "weapp-tw patch"
  }
}
```

> 这个补丁是为了让 `tailwindcss@4` 认识 `rpx` 单位，否则它会以为 `rpx` 是个颜色单位，导致 `text-[40rpx]` 这样的样式翻车。

---

### **2. 配置 `vite.config.ts`**

```ts title="vite.config.ts"

export default defineConfig(async () => {
  // 这里必须这样引用，因为 uni 只提供 cjs 版本，而 @tailwindcss/vite 只提供 esm 版本
  const { default: tailwindcss } = await import('@tailwindcss/vite')
  return {
    plugins: [
      uni(),
      tailwindcss(),
      UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true })
    ],
  }
})
```

---

### **3. 添加样式**

在项目目录下创建 `main.css`，然后添加以下内容：

```css title="main.css"
@import 'weapp-tailwindcss/index.css';
```

> **注意**：对于实际运行时入口，现在更推荐直接写 `@import 'weapp-tailwindcss/index.css'`，而不是继续依赖 `rewriteCssImports` 去改写 `@import 'tailwindcss'`。

接着在 `main.js` 里引用这个文件作为全局样式，然后直接运行：

```bash npm2yarn
npm run dev:mp-weixin
```

在微信开发者工具中导入这个项目，在项目中使用 `tailwindcss` 原子类，即可看到效果。

---

## **遇到的问题以及解决方案**

### **1. `tailwindcss@4` 的样式兼容性问题**

`tailwindcss@4` 生成的样式广泛使用了 `@layer`、`color-mix`、`oklch` 等新特性，现代浏览器兼容性都不咋地，更别说小程序了。

所以无论是 H5 还是小程序，都需要 `postcss-preset-env` 来降级这些样式的生成结果。降级的程度取决于你的 `browserslist` 配置。

---

### **2. `tailwind-merge` 样式合并问题**

`tailwind-merge` 是一个 `tailwindcss` 运行时样式合并工具，它能自动合并重复的样式。不过，小程序端用 `tailwind-merge` 有点挑战，因为：

- `weapp-tailwindcss` **在编译时** 对 `tailwindcss` 样式做转义。
- `tailwind-merge` **在运行时** 处理样式合并。

这导致 `tailwind-merge` 处理已转义的 `class` 时，误以为它们是普通 `class`，而不是 `tailwindcss` 的原子类。

### **解决方案：编译时感应 + 运行时合并转义**

我研究了一下 `tailwind-merge` 的源码，尝试写一个 `plugin` 来解决这个问题，结果发现路走不通，因为：

- `tailwind-merge` 内部有一些硬编码规则，比如 `!` 代表 `!important`，无法通过 `plugin` 自定义。

于是，我换了个思路，**采用编译时感应、忽略转义，运行时合并转义的方式** 解决了这个问题，这就是 **`@weapp-tailwindcss/merge`** 诞生的原因。

#### **编译时感应的原理**

我利用 `babel` 的 `scope`（作用域） 和 `binding`（绑定） 增强了识别能力

`scope` 简而言之就是 `js` 基础里的大括号, `binding` 就是一个变量真正的绑定

比如：

```js
const b = 'after:xx'
const a = `${b} text-[#123456]`
cn(a, 'xx', 'yy')
```

这段代码的作用域是全局，然后 `cn` 中 `a` 的绑定是一个 `VariableDeclaration` 它的 `init` 中，又引用了 `b` ，它的绑定也是一个 `VariableDeclaration` 初始化是一个 `StringLiteral`

于是，在编译时，我们可以从 `cn` 递归向上找到 `a` 和 `b`，识别出完整的样式链。

当然，另一种方式是 **自上而下查找**，通过 `import` 语句分析模块依赖关系，甚至可以利用打包工具的模块分析图进行静态分析。

当然这块的实现被用在了 **`@weapp-tailwindcss/merge`** 中，详见 [tailwind-merge 快速开始](https://tw.icebreaker.top/docs/community/merge)。

---

## **开发心得**

在开发的时候，一定要把可能影响结果的方式，拆成多多阶段运行，比如在修改 `js ast` 的时候，不应该一边 `traverse` ，一边再用 `MagicString` 去修改，而是应该把需要修改的地方，先全部收集出来，然后在一个阶段统一去修改。

另外鉴别一个 `ast` 工具的成熟度，也应该考虑一下，作用域和绑定的关系，能否被解析出来。比如我们都知道 `js` 里面大概有 `5` 种行为会产生作用域:

- **Program**：全局作用域，整个文件的顶层作用域。
- **FunctionDeclaration / FunctionExpression / ArrowFunctionExpression**：函数作用域（包括箭头函数）。
- **BlockStatement**：块级作用域（由 `{}` 包裹，例如 if、for、while 中的块，在 ES6 中支持 let 和 const）。
- **ClassDeclaration / ClassExpression**：类作用域（类的主体和方法会引入作用域）。
- **CatchClause**：try-catch 中 catch 块的作用域。

而绑定本身也是通过 `scope` 和它的 `parent` 依次向上去找的。

## 最后一点碎碎念

转眼我也到了而立之年，在这个行情下，毕业（失业）随时可能发生，当然也不敢毕业，毕竟上有老下有小，还有各种贷款。

技术学得越多，越觉得是个无底洞。而且掌握的东西多了，好像也没什么收益。更何况前端技术和那种 AI 技术相比，就像是过家家一样的。

开源呢？搞了半天也没啥产出，想成为开源明星，但自己技术水平也没到那个级别。

最近，我开始深入学习 **云原生**，因为我意识到，国内这种国情下 **"技术是工具，业务才是目的"**。

这导致我们技术人员的地位是非常低的，这点只要还在国内混就无法改变。

所以我们自己也不要对自己或者团队写的东西，搞得有多好多完美的似的。够用就行，多尝试，先快速搞他个 100 个应用，然后挑没死的去进行进一步的开发。

举个例子，现在让我从 0 到 1 搭建一个完整的业务系统，我可以全程自主搞定：

- **前端**：`Vue` / `React`
- **后端**：`Node.js`（任意框架）
- **数据库**：`MongoDB` / `PostgreSQL`
- **运维**：`Docker` / `Serverless`

但问题是——**开发成本和时间成本太高了！**

这种情况，我要自己去设计数据库，写 `openapi.yml` ，然后实现接口，还要自己写前端，和自己对接。写的差不多了还要测试，又是一堆 `bug`。

而且还可能遇到技术难点，之前我在 `Node.js` 中实现 `PostgreSQL` 的 `GraphQL` 方案，就折腾了好久。这种情况，为什么不直接上 `pg_graphql` 这种成熟的中间件呢？

所以，从商业角度来看：

1. **写尽可能少的代码**，尽量利用成熟方案快速搭建业务。
2. **赚钱才是第一要务**，哪里有问题，先堆机器解决，实在搞不定了，再招专业人才处理。
3. **多利用AI来降本增效**，AI 成本比人低，所以招个高级，不如招个初级的，会用 AI 的，学习能力好的程序员，毕竟前端静态页面，AI 生成可快了

所以，从一个程序员的视角出发:

**这是最好的时代，也是最坏的时代。**

---

## **参考链接**

- [weapp-tailwindcss 迁移文档](https://tw.icebreaker.top/docs/migrations/v3)
- [Tailwindcss@4 各个框架集成方式](https://tw.icebreaker.top/docs/quick-start/v4)
- [Tailwindcss@4 升级指南](https://tailwindcss.com/docs/upgrade-guide)
- [uni-app-tailwindcss-v4 参考模板](https://github.com/icebreaker-template/uni-app-tailwindcss-v4)

> 补充：classic `uni-app vue2 / webpack` 路线已经不再推荐，新项目请优先选择 `uni-app vue3 vite`。

---

## 4.2.0 🚀

weapp-tailwindcss@4.2.x 现已适配 `uni-app x` 的多端构建能力，让 Tailwind CSS 原子类能够无缝跨端使用。本文梳理了从项目初始化到插件配置的完整流程，帮助你快速完成集成与发布。

<!-- truncate -->

# weapp-tailwindcss 已支持 uni-app x 多端构建

## 前言

[`uni-app x`](https://doc.dcloud.net.cn/uni-app-x/) 是 `DCloud` 团队开发的跨平台编译方案，可将同一份代码编译到 Web、小程序、Android、iOS、鸿蒙等多端。

最近，我很荣幸在 `weapp-tailwindcss@4.2.x` 版本中，适配了 `uni-app x` 的多端构建，使 `Tailwind CSS` 的原子化样式能够无缝应用于多端项目。

所以就有了这篇文章，给大家介绍(**秀**)一下怎么在 `uni-app x` 项目中，集成 `weapp-tailwindcss` 这个样式解决方案。

## 快速集成

### 0. 创建项目

使用最新版本 `Hbuilderx` 创建一个 `uni-app x` 项目，然后在项目根目录执行

```bash
npm init -y
```

初始化一个 `package.json` 文件 (当然你也可以手动创建)

### 1. 安装并引入 tailwindcss@3

```bash
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
# 初始化一个 tailwind.config.js 文件
npx tailwindcss init
```

然后，在你的根目录中的 `App.uvue` 中引入 `tailwindcss` 使它在应用全局生效

```html title="App.uvue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

### 2. 安装 weapp-tailwindcss

在项目目录下，执行:

```bash
npm i -D weapp-tailwindcss
```

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

想知道原因的同学可以查看 [**这个链接**](https://tw.icebreaker.top/docs/quick-start/this-plugin)

### 3. uni-app x 中注册 weapp-tailwindcss

#### 3.0. 创建辅助函数

在项目中创建 `shared.js` 文件，用于存放一些工具函数：

```js title="shared.js"
const path = require('node:path')
// 绝对路径处理
function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = {
  r,
}
```

#### 3.1. 配置 `Vite`

创建 `vite.config.ts` 文件，注册插件：

> 这里特别注意 `uniAppX` 是从 `weapp-tailwindcss/presets` 这个预设中导出的

```js title="vite.config.ts"

export default defineConfig({
    plugins: [
        uni(),
        UnifiedViteWeappTailwindcssPlugin(
            uniAppX({
                base: __dirname,
                rem2rpx: true,
            }),
        ),
    ],
    css: {
        postcss: {
            plugins: [
                tailwindcss({
                    config: r('./tailwind.config.js'),
                }),
            ]
        }
    }
});
```

#### 3.2. 更改 `tailwindcss` 配置

你需要在 `tailwind.config.js` 的 `content` 配置中，使用绝对路径去包括所有的提取文件

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}') 
  ],
  corePlugins: {
    preflight: false,
  },
}

```

> 如需从更多目录提取样式 `token`，可按需扩展 `content`。

---

在完成这些步骤之后， `uni-app x` 就集成 `tailwindcss` 原子化样式解决方案。

## 如何运行

目前 `uni-app x` 并没有提供任何 `cli` 的方式去使用它，所以目前我们使用 `Hbuilderx` 去进行开发和构建的。

这里可以使用 `Hbuilderx` 的运行，来运行到各个平台。

### 优先使用安卓进行开发

一般来说，`CSS` 平台的兼容程度，是 `Web` > `小程序` > `App`(安卓/IOS/鸿蒙)

所以，假如你有跨多端的需求，建议你一开始使用 `安卓模拟器` 来进行开发和调试，这是综合考虑下来 **成本最低** 的方案。

#### 🧐为什么?

因为 `uni-app x` 开发原生 `app` 是有一些限制的，

1. 比如文字必须包括在 `<text>` 标签中，文字的样式(比如 `text-2xl text-center text-red-400`) 也必须设置在这个元素上，设置在 `<view>` 上是没有效果的。而 `Web` 和 `小程序` 都是兼容的。

2. 还有很多 `css` 的样式，目前 `uni-app x` 暂时是不兼容的，强行使用 `Hbuilderx` 的控制台会爆出警告，要求你进行更改。

这就相当于，你写的代码，能够满足了 `安卓` 这一端，那就大概率能满足 `小程序` 端，甚至 `Web` 端了(当然实战中还需要很多条件编译处理)

#### 🧐为什么不是 IOS 或者鸿蒙? 

IOS 模拟器，需要你有 Mac 才能运行，IOS 调试需要你有苹果手机，考虑到大部分开发应该都是用的 Windows 机器，所以选择 Android 模拟器开发，相对成本低一些，你都有的话当我没说

至于鸿蒙，uni-app x 官方文档上都写着:

> 鸿蒙整体处于发展初期，能用，有坑，大部分坑有规避方案。但开发者应建议其领导、客户、质量部门降低期望，不能严格比照Android和iOS的验收标准要求鸿蒙。

不如安卓/IOS 稳定的话，自然优先选择安卓平台

## 常见问题

### Vscode uvue/uts 代码染色

安装 `DCloud` 自己推出的 `uni-app x语言服务`, 插件市场一搜 `uni-app x` 就搜到了
- ID: dcloud-ide.hbuilderx-language-services
- 说明: 支持uni-app x项目的代码提示、悬浮、转到定义、查找引用、大纲、校验等
- 发布者: DCloud
- VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services

### Tailwindcss 智能提示

目前 `Tailwindcss` 智能提示最好的还是 `vscode`，但是 `vscode Tailwindcss` 肯定是不认识 `uvue/uts` 文件的，

要让插件认识，只需要在你的项目中添加 `.vscode/settings.json` 文件

```json
{
    "tailwindCSS.includeLanguages": {
        "uvue": "html",
        "uts": "javascript"
    }
}
```

当然，你直接全局修改你的 `vscode Tailwindcss` 插件配置肯定也是可以的。

## 尾言

`uni-app x` 是一个 **庞大的工程**, `DCloud` 团队能做出这样的技术解决方案，令人倾佩。

假如你遇到什么问题，可以在 [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss) 的 `issue/disscussions` 中提出。

## 配置好的模板

https://github.com/icebreaker-template/uni-app-x-hbuilderx

使用方式见这个项目中的 `README.md`

## 参考文档

[uni-app x 官方文档](https://doc.dcloud.net.cn/uni-app-x/)

[weapp-tailwindcss 官网](https://tw.icebreaker.top/)

[weapp-tailwindcss 的 uni-app x 专题](https://tw.icebreaker.top/docs/uni-app-x)

---

## 4.3.0 🚀

weapp-tailwindcss@4.3.0 默认开启 CSS 变量计算模式，并补充了更细粒度的 `cssCalc`、`px2rpx` 等配置，显著提升了多端 `rpx` 与 `calc` 的兼容性。本文带你了解这些变化的原理与使用方法。

<!-- truncate -->

# weapp-tailwindcss@4.3.0 🚀

## CSS变量计算模式

在 `tailwindcss@4` 下，默认启用 CSS 变量计算模式。`tailwindcss@3` 默认不启用。

此模式下会去预编译所有的 `css` 变量和 `calc` 计算表达式。

比如 `tailwindcss@4` 下原先生成的样式为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

在CSS变量计算模式启动，进行预编译之后，现在的结果为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
```

这个模式可以解决很多手机机型 `calc` `rpx` 单位的兼容问题

> 可通过给插件，传入 `cssCalc` 配置项 `false` 来手动关闭这个功能

假如这时候你需要去除 CSS 变量的声明，你可以传入

```js
{
  cssCalc: ['--spacing']
}
// 或者更精确的
{
  cssCalc: {
    includeCustomProperties: ['--spacing']
  }
}
```

> 你也可以传入正则表达式

这样生成的结果就是:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
}
```

通过这种方式可以解决手机机型 `calc` `rpx` 单位的兼容问题

详见: https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csscalc

## 新增配置项

### px2rpx

添加 `px2rpx` 配置项， 用于控制是否将 `px` 单位转换为 `rpx` 单位， 默认为 `false`

传入 `true` 则会将所有的 `px` 单位, `1:1` 转换为 `rpx` 单位

假如需要更多的转化方式，可以传入一个 `object`, 配置项见 https://www.npmjs.com/package/postcss-pxtransform

### logLevel

添加 `logLevel` 配置项，用于控制日志输出级别， 默认为 `info`