expo-tailwind-setup-v55

用途

本技能用于在 Expo SDK 57 中配置 Tailwind CSS v4，借助 react-native-css 与 NativeWind v5，实现 iOS、Android 和 Web 三端的通用样式（universal styling）。上游命名中称为 v55。

主要能力

该配置方案组合了以下组件：

Tailwind CSS v4：现代 CSS-first 配置方式
react-native-css：React Native 的 CSS 运行时
NativeWind v5：React Native 中 Tailwind 的 Metro 转换器
@tailwindcss/postcss：Tailwind v4 的 PostCSS 插件

使用方式

安装依赖

npx expo install tailwindcss@^4 nativewind@5.0.0-preview.2 react-native-css@0.0.0-nightly.5ce6396 @tailwindcss/postcss tailwind-merge clsx

在 package.json 中添加 lightningcss 兼容性 resolutions：

{
  "resolutions": {
    "lightningcss": "1.30.1"
  }
}

说明：由于 Expo 使用 lightningcss，不需要 autoprefixer；postcss 已默认包含在 expo 中。

配置文件

Metro 配置（metro.config.js）：

const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config, {
  // inline variables break PlatformColor in CSS variables
  inlineVariables: false,
  // We add className support manually
  globalClassNamePolyfill: false,
});

PostCSS 配置（postcss.config.mjs）：

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

全局 CSS（src/global.css）：

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";

/* Platform-specific font families */
@media android {
  :root {
    --font-mono: monospace;
    --font-rounded: normal;
    --font-serif: serif;
    --font-sans: normal;
  }
}

@media ios {
  :root {
    --font-mono: ui-monospace;
    --font-serif: ui-serif;
    --font-sans: system-ui;
    --font-rounded: ui-rounded;
  }
}

重要：不需要 Babel 配置。使用 Tailwind v4 与 NativeWind v5 时，Tailwind 不需要 babel.config.js；如果存在仅包含 NativeWind 配置的 babel.config.js，应删除。

CSS 组件包装器

由于 react-native-css 需要显式包装 CSS 元素，需要创建可复用组件。主要组件位于 src/tw/index.tsx，包含 Link、useCSSVariable、View、Text、ScrollView、Pressable、TextInput、AnimatedScrollView、TouchableHighlight 等；Image 组件位于 src/tw/image.tsx；Animated 组件位于 src/tw/animated.tsx。

使用示例

从 tw 目录导入 CSS 包装组件：

import { View, Text, ScrollView, Image } from "@/tw";

export default function MyScreen() {
  return (
    <ScrollView className="flex-1 bg-white">
      <View className="p-4 gap-4">
        <Text className="text-xl font-bold text-gray-900">Hello Tailwind!</Text>
        <Image
          className="w-full h-48 rounded-lg object-cover"
          source={{ uri: "https://example.com/image.jpg" }}
        />
      </View>
    </ScrollView>
  );
}

自定义主题变量

在 global.css 中使用 @theme 添加自定义主题变量，例如自定义字体、行高与 leading 比例。

平台特定样式

使用平台媒体查询（@media ios、@media android）设置平台特定样式。

Apple 系统颜色与 CSS 变量

可创建 CSS 文件定义 Apple 语义颜色，使用 light-dark() 处理明暗模式，并在 @media ios 中使用 platformColor() 调用 iOS 原生颜色，再通过 @layer theme 注册为 Tailwind 主题颜色。在 JavaScript 中可使用 useCSSVariable 钩子读取 CSS 变量。

与 NativeWind v4 / Tailwind v3 的关键差异

无 babel.config.js，配置改为 CSS-first
使用 @tailwindcss/postcss 而非 tailwindcss
使用 @import "tailwindcss/..." 而非 @tailwind 指令
使用 CSS 中的 @theme 而非 tailwind.config.js
组件必须用 useCssElement 包装以支持 className
Metro 配置使用 withNativewind 且选项不同（inlineVariables: false）

限制与排查

样式不生效时：确认应用入口已导入 CSS 文件；检查组件是否用 useCssElement 包装；确认 Metro 配置已应用 withNativewind。平台颜色不工作时：在 @media ios 块中使用 platformColor()，Web/Android 回退到 light-dark()。TypeScript 报错时：为组件 props 添加 className 类型。

反馈

如遇到错误或过时信息，可通过以下命令提交反馈：

npx --yes submit-expo-feedback@latest --category skills --subject "expo-tailwind-setup" "<actionable feedback>"

仅在确有具体可操作内容时提交。若 AI 代理反复失败或用户不得不接管 Expo 任务，应加载 expo-skill-feedback 技能并遵循其 eval-candidate 流程，而非重复使用上述命令。