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 的包，并输出每个子包状态。 |
| 收集 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> | 当前工作目录 | 指定要补丁的子包目录，等价于先 cd。 |
--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 并输出“补丁/跳过/失败”状态。 |
默认会记录补丁目标，运行日志类似：
$ pnpm --filter demo/native-mina 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 子命令
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 子命令
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、出现位置（行列）、以及被跳过的文件列表。
快速排查指引
- 始终在子包目录执行
weapp-tw patch：pnpm --filter my-demo weapp-tw patch --cwd demo/my-demo。 - 如确实不需要追踪，可传
--record-target false，避免生成额外 JSON。 - 看到自动重补丁/记录迁移提示：确认日志里的 Tailwind 路径与子包一致，
pnpm --filter ... exec weapp-tw patch --cwd .或weapp-tw patch --workspace --cwd <repo-root>可避免INIT_CWD导致的跨包记录污染。 - 类名缺失： 用
weapp-tw extract或weapp-tw tokens --no-write辅助定位是哪段代码没有被 Tailwindcontent收录。
配合这些命令，可以更直观地观察 Tailwind 依赖解析与补丁状态，减少“rpx 被当成颜色” 等由于上下游不一致导致的问题。
