docs: 补充 uni_modules content 扫描排障说明

Author: sonofmagic

website/docs/issues/index.md

@@ -49,6 +49,52 @@ keywords:
 
 如何更改？在传入的配置项 `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` 为例:

website/docs/quick-start/frameworks/uni-app-vite.md

@@ -53,6 +53,42 @@ export default defineConfig({
 
 这里只列举了插件的注册，包括`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` 的语法。

website/docs/quick-start/install.mdx

@@ -76,7 +76,11 @@ module.exports = {
 module.exports = {
   // 这里给出了一份 uni-app /taro 通用示例，具体要根据你自己项目的目录结构进行配置
   // 不在 content 包括的文件内，你编写的 class，是不会生成对应的css工具类的
-  content: ['./public/index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'],
+  content: [
+    './public/index.html',
+    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+    '!./src/uni_modules/**/*',
+  ],
   // 其他配置项
   // ...
   corePlugins: {
@@ -86,6 +90,52 @@ module.exports = {
 }
 ```
 
+### `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` 使它在小程序全局生效