expo-tailwind-setup

用途

该技能提供在 Expo 项目中使用 Tailwind CSS v4 的完整配置指南，借助 react-native-css 与 NativeWind v5，实现 iOS、Android 和 Web 三端的通用样式（universal styling）。

主要能力

使用 Tailwind CSS v4 的 CSS-first 配置方式。
通过 react-native-css 提供 React Native 的 CSS 运行时。
通过 NativeWind v5 作为 React Native 中 Tailwind 的 Metro transformer。
使用 @tailwindcss/postcss 作为 Tailwind v4 的 PostCSS 插件。
支持自定义主题变量、平台特定样式、Apple 系统颜色以及 CSS 变量在 JavaScript 中的使用。

使用方式

安装依赖

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;
  }
}

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

CSS 组件包装器

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

主组件（src/tw/index.tsx）使用 useCssElement 与 useNativeVariable 包装 Link、View、Text、ScrollView、Pressable、TextInput、AnimatedScrollView、TouchableHighlight 等，并为每个组件添加 className 支持。

Image 组件（src/tw/image.tsx）基于 expo-image 与 react-native-reanimated，将 objectFit / objectPosition 映射为 contentFit / contentPosition。

Animated 组件（src/tw/animated.tsx）导出带有动画能力的 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 媒体查询设置平台特定样式。

Apple 系统颜色与 CSS 变量

可创建 CSS 文件定义 Apple 语义颜色，使用 light-dark() 提供明暗模式，并在 @media ios 中使用 platformColor() 调用 iOS 原生颜色，再通过 @theme 注册为 Tailwind 主题颜色。

在 JavaScript 中使用 useCSSVariable hook 读取 CSS 变量。

与 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 项目中跨 iOS、Android 和 Web 使用统一 Tailwind 样式体系的开发场景。

限制与排查

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

关于该技能的收费、价格、平台支持范围等更多信息，资料中暂未提供。