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 插件

支持自定义主题变量、平台特定样式（通过 @media ios / @media android 媒体查询）、Apple 系统语义颜色（含 platformColor 与 light-dark 回退），以及在 JavaScript 中通过 useCSSVariable 钩子读取 CSS 变量。

使用方式

安装依赖

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）：使用 withNativewind 包装默认配置，并设置 inlineVariables: false（内联变量会破坏 CSS 变量中的 PlatformColor）以及 globalClassNamePolyfill: false（手动添加 className 支持）。

PostCSS 配置（postcss.config.mjs）：注册 @tailwindcss/postcss 插件。

全局 CSS（src/global.css）：通过 @import 引入 tailwindcss/theme.css、preflight.css、utilities.css，并可按平台定义字体族变量。

重要：使用 Tailwind v4 与 NativeWind v5 时，Tailwind 不再需要 babel.config.js，应移除任何 NativeWind babel preset。

CSS 组件包装器

由于 react-native-css 需要显式包装 CSS 元素，需创建可复用组件：

src/tw/index.tsx：包装 Link、View、Text、ScrollView、Pressable、TextInput、AnimatedScrollView、TouchableHighlight，并提供 useCSSVariable 钩子
src/tw/image.tsx：包装 expo-image 的 Image，将 objectFit/objectPosition 映射为 contentFit/contentPosition
src/tw/animated.tsx：导出 Animated 及 Animated.View

使用示例：

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 设置 :root 变量。Apple 系统颜色可定义在独立 CSS 文件中，iOS 下使用 platformColor()，Web/Android 下回退到 light-dark()，并通过 @theme 注册为 Tailwind 主题颜色（如 text-sf-text、bg-sf-bg）。

在 JavaScript 中使用 CSS 变量：

import { useCSSVariable } from "@/tw";

function MyComponent() {
  const blue = useCSSVariable("--sf-blue");
  return <View style={{ borderColor: blue }} />;
}

与 NativeWind v4 / Tailwind v3 的关键差异

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

适用场景

适用于需要在 Expo SDK 57 项目中跨 iOS、Android、Web 使用统一 Tailwind 样式体系的开发场景，尤其是希望采用 CSS-first 配置、自定义主题变量与平台特定样式的项目。

限制与排查

样式不生效：确认应用入口已导入 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 流程。