tailwind-capacitor

Capacitor 应用中的 Tailwind CSS

适用场景

在以下情况使用：

• 在 Capacitor 应用中添加 Tailwind（Vite、Angular、Next 静态导出等）
• 将 Tailwind v3 升级到 v4，或安装 v4 后没有生成样式
• 修改 tailwind.config.js 后没有效果（v4 采用 CSS 优先配置）
• 颜色／渐变异常，或在较旧的 iOS 设备上变透明
• 安全区域、深色模式、平台特定样式或触控目标工具类

请勿用于：

• Konsta UI 设置／组件：konsta-ui
• Ionic 组件和 --ion-* 变量：ionic-design
• SystemBars／Android 全屏显示／状态栏插件：safe-area-handling
• 被键盘遮挡的输入框：capacitor-keyboard
• 将 Capacitor 添加到框架：framework-to-capacitor

版本信息（2026 年 10 月）

• tailwindcss 4.x 是 latest（4.3.x）；3.4.x 位于 v3-lts。
• v4 在 CSS 中配置。除非添加 @config "./tailwind.config.js";，否则不会读取 tailwind.config.js。
• v4 的目标版本为 Safari 16.4+、Chrome 111+、Firefox 128+（使用 @property、color-mix()、级联层和 oklch）。
• Capacitor 8 支持 iOS 15+，Capacitor 9 支持 iOS 16+。WKWebView = 设备上的 Safari 版本。**运行 iOS 15.x - 16.3 的设备会错误渲染 v4 样式。**Android System WebView 会自动更新，因此通常能满足 Chrome 111+ 的要求（Capacitor 9 的 minSdk 为 26）。

决策：如果 iOS 部署目标（或实际用户群）包含 iOS < 16.4，请询问用户：继续使用 Tailwind 3.4，还是提高最低 OS 版本。不要在未告知的情况下直接发布 v4。

工作流

1. 检查：npm ls tailwindcss、tailwind.config.*、postcss.config.*、打包工具配置、主 CSS 文件、ios/App/App.xcodeproj 中的 IPHONEOS_DEPLOYMENT_TARGET，以及是否存在 Ionic 或 Konsta。
2. 全新安装（见下文）或升级：references/v3-to-v4.md。
3. 移动端工具类（安全区域、平台变体、触控、深色模式）：references/mobile-patterns.md。
4. 验证（见下文）。

仅在涉及相应主题时加载参考资料。

安装（Vite：React、Vue、Svelte、Solid）

npm i tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [tailwindcss() /* + framework plugin */] });

/* src/styles.css */
@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant ios (&:where(.plt-ios, .plt-ios *));
@custom-variant android (&:where(.plt-android, .plt-android *));

@theme {
  --color-brand: oklch(0.55 0.2 265);
  --font-sans: system-ui, -apple-system, "Roboto", sans-serif;
}

@utility pt-safe { padding-top: env(safe-area-inset-top); }
@utility pb-safe { padding-bottom: env(safe-area-inset-bottom); }
@utility px-safe { padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); }

其他工具链：PostCSS（Angular、webpack、Next）→ npm i tailwindcss @tailwindcss/postcss，并在 postcss.config.mjs 中配置 { plugins: { "@tailwindcss/postcss": {} } }；独立使用 → @tailwindcss/cli。Angular CLI 17+ 会读取 .postcssrc.json。

// main.ts: platform class for ios:/android: variants
import { Capacitor } from '@capacitor/core';
document.documentElement.classList.add(`plt-${Capacitor.getPlatform()}`); // plt-ios | plt-android | plt-web

在视口 meta 标签中添加 viewport-fit=cover，否则安全区域工具类会解析为 0。

注意事项

• v4 会自动检测内容（遵循 .gitignore）。node_modules 中或项目根目录外的类需要使用 @source "../path";。动态类名（`bg-${color}-500`）永远不会生成；应映射到完整的类名字符串。
• v4 中的 hover: 只会应用于符合 (hover: hover) 的设备，因此默认解决了触屏设备上的 hover 状态粘滞问题。按压反馈请使用 active:。
• v4 的默认值已更改：边框颜色为 currentColor，ring 为 1px，shadow-sm／shadow 和 rounded-sm／rounded 的尺寸级别已调整，outline-none 变为 outline-hidden。升级工具会重命名大部分内容；请目视检查。
• Ionic + Tailwind：Preflight 会重置 Ionic 排版。导入不含 Preflight 的 Tailwind（@layer theme, base, components, utilities; @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/utilities.css" layer(utilities);），或在 Tailwind 之后加载 Ionic CSS。
• Konsta UI v5 已通过 konsta/<fw>/theme.css 导入 Tailwind 主题的相关部分；请按 konsta-ui 的说明操作，避免重复设置。
• 全屏布局不要使用 100vh；请使用 h-dvh（v4 提供 dvh／svh／lvh 工具类）或 flex 容器。
• Android WebView < 140 会将安全区域 env() 报告为 0；Capacitor 8 SystemBars 会注入 --safe-area-inset-*。为确保 Android 上可靠运行，请使用 @utility pt-safe { padding-top: var(--safe-area-inset-top, env(safe-area-inset-top)); }（参见 safe-area-handling）。

验证

1. npm run build 成功；构建后的 CSS 包含你的工具类：grep -c "pt-safe" dist/assets/*.css。
2. 执行 npx cap sync 并在以下设备上运行：支持的最低 iOS 版本（检查颜色、渐变和阴影的渲染效果）、当前款 iPhone、Android 15/16。
3. 切换深色模式类和操作系统外观；检查 <html class>，确认 ios:/android: 变体。
4. 升级后检查是否有残留：grep -rn "@tailwind base\|@tailwind components\|@tailwind utilities\|require('tailwindcss')" src postcss.config.* 2>/dev/null 不应返回任何内容。

错误处理

错误 / 现象	原因	修复方法
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package	使用 v4 时仍采用 v3 风格的 PostCSS 配置	使用 @tailwindcss/postcss（或 @tailwindcss/vite）
完全没有样式	缺少 @import "tailwindcss" 或打包工具插件	两者都添加
在 @apply 中出现 Cannot apply unknown utility class	自定义类未通过 @utility 定义，或 CSS 模块 / Vue <style> 中未引用主题	使用 @utility 定义；在作用域样式中添加 @reference "../styles.css";
忽略 tailwind.config.js 主题更改	v4 不会自动加载 JS 配置	迁移到 @theme，或添加 @config
部分 iPhone 上颜色透明或缺失	iOS < 16.4 不支持 v4 使用的功能	提高最低 iOS 版本，或继续使用 3.4
dark: 跟随操作系统设置，忽略切换	默认深色模式变体基于媒体查询	添加 @custom-variant dark (&:where(.dark, .dark *));
升级工具失败：需要 Node	@tailwindcss/upgrade 需要 Node 20+	升级 Node（无论如何，Capacitor 9 都需要 24+）

资源

• Tailwind v4 安装（Vite）：https://tailwindcss.com/docs/installation/using-vite
• 升级指南：https://tailwindcss.com/docs/upgrade-guide
• 主题变量：https://tailwindcss.com/docs/theme
• 浏览器支持：https://tailwindcss.com/docs/compatibility
• 深色模式：https://tailwindcss.com/docs/dark-mode