weapp-tw CLI 使用指南

@weapp-tailwindcss/cli 独立发布 weapp-tw 和 weapp-tailwindcss 两个等价命令。构建命令默认输出 Web CSS，并对齐当前 Tailwind CSS CLI 的输入、输出、watch、优化和 source map 行为。

注意：npm 上的 3.x 与 4.0.0-alpha.x 是旧版原生小程序 Gulp 工具链。本 CLI 的新实现从 5.x 版本线开始发布；升级时请按本文档配置 CSS 输入，不再使用旧版 init、Sass/Less 编译或项目目录扫描流程。

CLI 直接复用 weapp-tailwindcss 的 Tailwind v4 generator、design system 与 source graph，不安装或调用 @tailwindcss/cli。watch 默认使用 @parcel/watcher 原生文件事件；在容器、网络文件系统或需要稳定轮询行为时，可使用 --poll[=ms] 切换到轮询模式。

安装

pnpm add -D @weapp-tailwindcss/cli weapp-tailwindcss tailwindcss

其中 @weapp-tailwindcss/cli 提供命令层，weapp-tailwindcss 提供生成和 CSS 转换能力，项目使用的 Tailwind CSS v4 由 tailwindcss 提供。

pnpm exec weapp-tw -i src/input.css -o dist/output.css
pnpm exec weapp-tw build -i src/input.css -o dist/output.css

构建参数

参数	简写	说明
--input <file>	-i	输入 CSS；传 - 时读取 stdin。省略时使用 @import "tailwindcss";。
--output <file>	-o	输出 CSS；默认或传 - 时写入 stdout。
--watch[=always]	-w	监听依赖并增量重建；always 会在 stdin 关闭后继续监听。
--poll[=ms]		watch 时使用轮询而不是原生 watcher；不传间隔时默认 250ms。
--minify	-m	优化并压缩 CSS。
--optimize		优化 CSS，但不压缩。
--cwd <dir>		设置输入、输出和依赖解析的工作目录。
--map[=<file>]		不传路径时内联 source map，传路径时写入独立 map 文件。
--silent		隐藏非错误构建日志。
--target web|weapp		输出目标，默认 web。

stdin 与 stdout 可以组合使用：

pnpm exec weapp-tw -i - -o - --minify < src/input.css > dist/output.css

监听模式：

pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch
pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch --poll=100

小程序 CSS 目标

显式传入 --target weapp 后，CLI 会先生成 Tailwind CSS，再调用 weapp-tailwindcss 的 CSS 兼容转换链路：

pnpm exec weapp-tw -i src/input.css -o dist/app.wxss --target weapp

CSS-only 边界

--target weapp 只转换 CSS，不扫描或改写 WXML、JS、TS、JSX、TSX。完整小程序项目仍应使用 weapp-tailwindcss/vite、Webpack、Rspack 或 Gulp 集成，使模板、脚本和样式共享同一个 classNameSet 与构建生命周期。

转换后的 CSS 与 Web CSS 行号不再一一对应，因此 --target weapp 不支持 --map。

canonicalize

canonicalize 使用 Tailwind design system 合并等价工具类，并输出规范候选：

pnpm exec weapp-tw canonicalize "py-3 p-1 px-3"
# p-3

printf 'py-3 p-1 px-3\nmt-2 mr-2 mb-2 ml-2\n' \
  | pnpm exec weapp-tw canonicalize --stream

可通过 --css <file> 加载自定义 theme、plugin 和 config，并通过 --format text|json|jsonl 选择输出格式。

兼容与辅助命令

命令	用途
weapp-tw doctor [--json] [--strict]	检查项目配置。
weapp-tw vscode-entry --css <file>	生成 Tailwind IntelliSense 辅助入口。
weapp-tw patch / install	v5 兼容 no-op；应从 postinstall 中移除。
weapp-tw status [--json]	返回 patch 已不再需要的兼容状态。

常见错误

• 输入与输出解析到同一文件时命令会失败，避免覆盖入口 CSS。
• --poll 必须是大于 0 的毫秒数。
• --map=- 不表示 inline map；请直接传 --map。
• Windows、macOS 与 Linux 均按当前平台的文件系统路径解析，不要在脚本中手动拼接 /。