docs: 补充 uni-app uni_modules 扫描排除说明

sonofmagic · sonofmagic · commit a0733eca2b25 · 2026-04-03T16:12:24.000+08:00
diff --git a/apps/tailwindcss-weapp/tailwind.config.js b/apps/tailwindcss-weapp/tailwind.config.js
@@ -5,7 +5,11 @@ const { isMp } = require('./platform')
 
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-  content: ['./index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'],
+  content: [
+    './index.html',
+    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+    '!./src/uni_modules/**/*',
+  ],
   // https://tailwindcss.com/docs/dark-mode
   // darkMode: 'class',
   // darkMode: ['variant', ['&:is(.dark *)']],
diff --git a/demo/uni-app-tailwindcss-v4/src/main.css b/demo/uni-app-tailwindcss-v4/src/main.css
@@ -1,6 +1,7 @@
 /* stylelint-disable custom-property-pattern */
 @import "weapp-tailwindcss";
 @config "../tailwind.config.js";
+@source not "../src/uni_modules";
 
 @theme {
   --color-neutral-1B: #1b1b1b;
diff --git a/demo/uni-app-tailwindcss-v4/src/tailwind-intellisense.css b/demo/uni-app-tailwindcss-v4/src/tailwind-intellisense.css
@@ -1,2 +1,3 @@
 @import "tailwindcss";
 @source not "dist";
+@source not "../src/uni_modules";
diff --git a/demo/uni-app-vue3-vite/tailwind.config.js b/demo/uni-app-vue3-vite/tailwind.config.js
@@ -12,7 +12,11 @@ const cssMacro = require('weapp-tailwindcss/css-macro');
 const { plugin: tailwindcssChildrenPlugin } = require('weapp-tailwindcss-children');
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-  content: ['./index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'].map((x) => r(x)), // ,
+  content: [
+    './index.html',
+    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+    '!./src/uni_modules/**/*',
+  ].map((x) => x.startsWith('!') ? `!${r(x.slice(1))}` : r(x)), // ,
   darkMode: 'class',
   // important: '.app',
   theme: {
diff --git a/demo/uni-app-x-hbuilderx-tailwindcss3/tailwind.config.js b/demo/uni-app-x-hbuilderx-tailwindcss3/tailwind.config.js
@@ -4,6 +4,7 @@ const { r } = require('./shared')
 module.exports = {
   content: [
     r('./pages/**/*.{uts,uvue}'),
+    `!${r('./uni_modules/**/*')}`,
   ],
   theme: {
     extend: {},
diff --git a/demo/uni-app-x-hbuilderx-tailwindcss4/main.css b/demo/uni-app-x-hbuilderx-tailwindcss4/main.css
@@ -1,2 +1,3 @@
 @import 'weapp-tailwindcss/uni-app-x';
 @source not "unpackage";
+@source not "uni_modules";
diff --git a/demo/uni-app-x-hbuilderx-tailwindcss4/tailwind-intellisense.css b/demo/uni-app-x-hbuilderx-tailwindcss4/tailwind-intellisense.css
@@ -1,2 +1,3 @@
 @import "tailwindcss";
 @source not "unpackage";
+@source not "uni_modules";
diff --git a/templates/uni-app-hbuilderx-tailwindcss-v4/main.css b/templates/uni-app-hbuilderx-tailwindcss-v4/main.css
@@ -1,2 +1,3 @@
 @import "tailwindcss";
-@source not "unpackage";
+@source not "unpackage";
+@source not "uni_modules";
diff --git a/templates/uni-app-tailwindcss-v4/src/main.css b/templates/uni-app-tailwindcss-v4/src/main.css
@@ -1,2 +1,3 @@
 @import "tailwindcss";
-@source not "dist";
+@source not "dist";
+@source not "../src/uni_modules";
diff --git a/templates/uni-app-vite-vue3-tailwind-vscode-template/tailwind.config.ts b/templates/uni-app-vite-vue3-tailwind-vscode-template/tailwind.config.ts
@@ -4,7 +4,11 @@ import cssMacro from 'weapp-tailwindcss/css-macro'
 import { isMp } from './platform'
 
 export default <Config>{
-  content: ['./index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'],
+  content: [
+    './index.html',
+    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+    '!./src/uni_modules/**/*',
+  ],
   theme: {
     extend: {
       // colors: {
diff --git a/templates/uni-app-vue2-tailwind-hbuilder-template/tailwind.config.js b/templates/uni-app-vue2-tailwind-hbuilder-template/tailwind.config.js
@@ -11,6 +11,7 @@ module.exports = {
       resolve("./pages/**/*.{vue,js,ts,jsx,tsx,wxml}"),
       resolve("./pagesA/**/*.{vue,js,ts,jsx,tsx,wxml}"),
       resolve("./pagesB/**/*.{vue,js,ts,jsx,tsx,wxml}"),
+      `!${resolve("./uni_modules/**/*")}`,
     ],
   },
   darkMode: false, // or 'media' or 'class'
diff --git a/templates/uni-app-vue2-tailwind-vscode-template/tailwind.config.js b/templates/uni-app-vue2-tailwind-vscode-template/tailwind.config.js
@@ -3,7 +3,11 @@ const cssMacro = require('weapp-tailwindcss/css-macro')
 // https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/blob/main/demo/uni-app/tailwind.config.js
 /** @type {import('@types/tailwindcss/tailwind-config').TailwindConfig} */
 module.exports = {
-  content: ['public/index.html', './src/**/*.{vue,js,ts,jsx,tsx,wxml}'],
+  content: [
+    'public/index.html',
+    './src/**/*.{vue,js,ts,jsx,tsx,wxml}',
+    '!./src/uni_modules/**/*',
+  ],
   theme: {
     extend: {}
   },
@@ -30,4 +34,4 @@ module.exports = {
   corePlugins: {
     preflight: false
   }
-}
+}
diff --git a/templates/uni-app-vue3-tailwind-hbuilder-template/tailwind.config.js b/templates/uni-app-vue3-tailwind-hbuilder-template/tailwind.config.js
@@ -2,7 +2,11 @@ const { resolve, isMp } = require('./shared')
 const cssMacro = require('weapp-tailwindcss/css-macro')
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-  content: ["./index.html", "pages/**/*.{vue,ts,js,wxml}"].map(resolve),
+  content: [
+    "./index.html",
+    "pages/**/*.{vue,ts,js,wxml}",
+    "!./uni_modules/**/*",
+  ].map((x) => x.startsWith('!') ? `!${resolve(x.slice(1))}` : resolve(x)),
   theme: {
     extend: {
       colors: {
diff --git a/templates/uni-app-webpack-tailwindcss-v4/src/main.css b/templates/uni-app-webpack-tailwindcss-v4/src/main.css
@@ -1 +1,3 @@
-@import "tailwindcss";
+@import "tailwindcss";
+@source not "dist";
+@source not "../src/uni_modules";
diff --git a/templates/uni-app-x-hbuilderx/tailwind.config.js b/templates/uni-app-x-hbuilderx/tailwind.config.js
@@ -5,6 +5,7 @@ module.exports = {
   content: [
     r('./pages/**/*.{uts,uvue}'),
     r('./components/**/*.{uts,uvue}'),
+    `!${r('./uni_modules/**/*')}`,
   ],
   theme: {
     extend: {},
diff --git a/website/docs/quick-start/v4/UniappCliStyle.mdx b/website/docs/quick-start/v4/UniappCliStyle.mdx
@@ -41,6 +41,7 @@ import UniAppUniScss from '../_UniAppUniScss.mdx'
 ```css title="src/main.css"
 @import "tailwindcss";
 @source not "dist";
+@source not "../src/uni_modules";
 ```
 
 然后把 `experimental.configFile` 指向它：
@@ -53,6 +54,32 @@ import UniAppUniScss from '../_UniAppUniScss.mdx'
 
 这个 `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"`。
 
 <UniAppUniScss/>
diff --git a/website/docs/quick-start/v4/UniappHbuilderStyle.mdx b/website/docs/quick-start/v4/UniappHbuilderStyle.mdx
@@ -41,6 +41,7 @@ import UniAppUniScss from '../_UniAppUniScss.mdx'
 ```css title="src/main.css"
 @import "tailwindcss";
 @source not "unpackage";
+@source not "uni_modules";
 ```
 
 然后把 `experimental.configFile` 指向它：
@@ -53,8 +54,34 @@ import UniAppUniScss from '../_UniAppUniScss.mdx'
 
 这个 `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 "unpackage";` 是为了避免 `HBuilderX` 差量编译死循环问题；再加上 `@source not "uni_modules";`，则可以避免把第三方依赖源码一并扫进 Tailwind 4 的候选集合。
 
 <UniAppUniScss/>
diff --git a/website/docs/quick-start/v4/readme.md b/website/docs/quick-start/v4/readme.md
@@ -199,6 +199,7 @@ shamefully-hoist=true
 ```css title="main.css"
 @import "tailwindcss";
 @source not "dist";
+@source not "../src/uni_modules";
 ```
 
 ```json title=".vscode/settings.json"
@@ -222,6 +223,50 @@ shamefully-hoist=true
 
 如果你的项目不是 `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 样式
diff --git a/website/static/llms-index.json b/website/static/llms-index.json
@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2026-04-01T16:03:32.865Z",
+  "generatedAt": "2026-04-03T08:06:18.764Z",
   "siteUrl": "https://tw.icebreaker.top",
   "totals": {
     "all": 175,
@@ -2869,10 +2869,10 @@
         "`disabled:opacity-50` 这类的 `tailwindcss` 工具类不生效?",
         "`background-image` 为什么不能使用本地路径？",
         "和原生组件一起使用注意事项",
-        "编译到 h5 / app 注意事项",
-        "报错 TypeError: Cannot use 'in' operator to search for 'CallExpression' in undefined",
-        "taro webpack5 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效",
-        "为什么 space-y-1 这类写法不起作用?"
+        "uni-app + Tailwind CSS v3 扫描 `src/uni_modules` 后生成异常 CSS",
+        "# 问题现象",
+        "# 根因",
+        "# 推荐配置"
       ],
       "updatedAt": null,
       "source": "docs/issues/index.md"
@@ -4147,6 +4147,11 @@
       ],
       "headings": [
         "注册插件",
+        "`tailwind.config` 扫描范围提醒",
+        "# 问题现象",
+        "# 根因",
+        "# 推荐配置",
+        "# 最佳实践",
         "创建项目参考",
         "视频演示"
       ],
@@ -4252,10 +4257,11 @@
         "1. 使用包管理器安装 `tailwindcss`",
         "2. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss`",
         "3. 配置 `tailwind.config.js`",
-        "4. 引入 `tailwindcss`",
-        "# uni-app",
-        "# Taro",
-        "参考链接"
+        "# `content` 扫描范围排障",
+        "## 问题现象",
+        "## 根因",
+        "## 推荐配置",
+        "## 最佳实践"
       ],
       "updatedAt": null,
       "source": "docs/quick-start/install.mdx"
@@ -4951,7 +4957,13 @@
         "rax",
         "mpx"
       ],
-      "headings": [],
+      "headings": [
+        "`@source` 扫描范围排障",
+        "# 问题现象",
+        "# 根因",
+        "# 推荐配置",
+        "# 最佳实践"
+      ],
       "updatedAt": null,
       "source": "docs/quick-start/v4/UniappCliStyle.mdx"
     },
@@ -4985,6 +4997,7 @@
         "1. 安装",
         "2. 添加 `vite.config.ts`",
         "3. 添加样式",
+        "布局限制",
         "参考模板"
       ],
       "updatedAt": null,
@@ -5014,7 +5027,13 @@
         "rax",
         "mpx"
       ],
-      "headings": [],
+      "headings": [
+        "`@source` 扫描范围排障",
+        "# 问题现象",
+        "# 根因",
+        "# 推荐配置",
+        "# 最佳实践"
+      ],
       "updatedAt": null,
       "source": "docs/quick-start/v4/UniappHbuilderStyle.mdx"
     },
@@ -6022,10 +6041,10 @@
         "你将收获什么",
         "最快开始",
         "开发建议（从用户出发）",
+        "布局能力边界",
         "为什么推荐先用 Android",
         "常见问题",
-        "# VS Code 对 uvue/uts 的高亮与跳转",
-        "# Tailwind CSS 智能提示"
+        "# VS Code 对 uvue/uts 的高亮与跳转"
       ],
       "updatedAt": null,
       "source": "docs/uni-app-x/index.mdx"

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`@import "tailwindcss";`
`2`	`2`	`@source not "dist";`
	`3`	`+@source not "../src/uni_modules";`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`@import 'weapp-tailwindcss/uni-app-x';`
`2`	`2`	`@source not "unpackage";`
	`3`	`+@source not "uni_modules";`