Tailwind CSS

编辑页面

了解如何在你的 Expo 项目中配置和使用 Tailwind CSS。

标准 Tailwind CSS 仅支持 Web 平台。若要获得通用支持，请使用类似 NativeWind 或 Uniwind 这样的库，它们允许使用 Tailwind CSS 创建带样式的 React Native 组件。

Tailwind CSS 是一个实用优先的 CSS 框架，可与 Metro 一起用于 Web 项目。本指南将说明如何配置你的 Expo 项目以使用该框架。

Prerequisites

1 requirement

使用 Metro 进行 Web 构建的项目

确保你的项目正在为 Web 使用 Metro。通过检查 app.json 中的 web.bundler 是否设置为 metro 来验证这一点：

app.json

{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}

将修改以下文件以设置 Tailwind CSS 配置：

app.json

package.json

global.css

index.js

配置

请根据 Tailwind PostCSS 文档在你的 Expo 项目中配置 Tailwind CSS。

安装 tailwindcss 及其所需的同级依赖。然后运行初始化命令，在项目根目录中创建 tailwind.config.js 和 post.config.js 文件。

Terminal

# 安装 Tailwind 及其同级依赖

- npx expo install tailwindcss@3 postcss autoprefixer --dev

# 创建 Tailwind 配置文件

- npx tailwindcss init -p

将所有模板文件的路径添加到 tailwind.config.js 中。

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // 确保这里指向你的源代码
    './src/app/**/*.{js,tsx,ts,jsx}',
    // 如果你使用 `src` 目录，请添加：'./src/**/*.{js,tsx,ts,jsx}'
    // 对 `components`、`hooks`、`styles` 或任何其他顶级目录也同样处理
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

如果你正在使用 Expo Router，建议使用根级 src 目录来简化这一步。了解更多关于顶级 src 目录的信息。

在项目根目录创建一个 global.css 文件，并为 Tailwind 的每一层添加指令：

global.css

/* 此文件添加 Tailwind 正常工作所需的实用类。 */
@tailwind base;
@tailwind components;
@tailwind utilities;

在你的 src/app/_layout.tsx（如果使用 Expo Router）或 index.js 文件中导入 global.css 文件：

src/app/_layout.tsx

import '../../global.css';

index.js

// 在 index.js 文件中导入 global.css 文件：
import './global.css';

如果你正在使用 DOM 组件，由于它们不共享全局变量，请将此文件导入添加到每个使用 "use dom" 指令的模块中。

始终在根级 _layout.tsx 中导入全局 CSS，而不是在嵌套布局中。Expo Router 会从根布局开始遍历依赖图。在嵌套布局中导入 CSS（例如 app/blog/_layout.tsx）会导致 node_modules 中的 CSS 先于你的自定义样式加载，这可能会破坏你期望的样式顺序。

现在启动你的项目，并在组件中使用 Tailwind CSS 类。

Terminal

- npx expo start

安装 tailwindcss 及其所需的同级依赖：

Terminal

# 安装 Tailwind 及其同级依赖

- npx expo install tailwindcss @tailwindcss/postcss postcss --dev

将 Tailwind 添加到你的 PostCSS 配置中

postcss.config.mjs

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

创建一个导入 Tailwind CSS 的全局 CSS 文件。

你可以为此文件选择任意名称。使用 global.css 是常见做法。

global.css

@import 'tailwindcss';

在你的 src/app/_layout.tsx（如果使用 Expo Router）或 index.js 文件中导入你的 CSS 文件：

src/app/_layout.tsx

// 如果使用 Expo Router，请在 src/app/_layout.tsx 文件中导入你的 CSS 文件
import '../../global.css';

index.js

// 否则在 index.js 文件中导入你的 CSS 文件：
import './global.css';

如果你正在使用 DOM 组件，由于它们不共享全局变量，请将此文件导入添加到每个使用 "use dom" 指令的模块中。

始终在根级 _layout.tsx 中导入全局 CSS，而不要在嵌套布局中导入。Expo Router 会从根布局开始遍历依赖图。在嵌套布局中导入 CSS（例如 app/blog/_layout.tsx）会导致 node_modules 中的 CSS 先于你的自定义样式加载，这可能会破坏你期望的样式顺序。

现在启动你的项目，并在组件中使用 Tailwind CSS 类。

Terminal

- npx expo start

用法

你可以直接在 React DOM 元素中使用 Tailwind：

src/app/index.tsx

export default function Index() {
  return (
    <div className="bg-slate-100 rounded-xl">
      <p className="text-lg font-medium">欢迎使用 Tailwind</p>
    </div>
  );
}

你可以使用 { $$css: true } 语法将 Tailwind 与 React Native web 元素一起使用：

src/app/index.tsx

import { View, Text } from 'react-native';

export default function Index() {
  return (
    <View style={{ $$css: true, _: 'bg-slate-100 rounded-xl' }}>
      <Text style={{ $$css: true, _: 'text-lg font-medium' }}>欢迎使用 Tailwind</Text>
    </View>
  );
}

Android 和 iOS 的 Tailwind

Tailwind 不支持 Android 和 iOS 平台。你可以使用兼容性库，例如 NativeWind 或 Uniwind，以获得跨平台支持。

面向 AI 代理的 Expo Skills

如果你使用 AI 代理，请安装 Expo Skills，以教会它进行通用的 Tailwind CSS 设置：

expo-tailwind-setup

Set up Tailwind CSS v4 in Expo with react-native-css and NativeWind v5 for universal styling.

Android 和 iOS 的替代方案

或者，你可以使用 DOM 组件在原生环境中的 WebView 里渲染你的 Tailwind Web 代码。

src/app/index.tsx

'use dom';

// 记得在每个 DOM 组件中导入 global.css 文件。
import '../../global.css';

export default function Page() {
  return (
    <div className="bg-slate-100 rounded-xl">
      <p className="text-lg font-medium">欢迎使用 Tailwind</p>
    </div>
  );
}

故障排查

如果你在 metro.config.js 中自定义了 config.cacheStores，你需要扩展 FileStore 的 Expo 超类：

metro.config.js

// 导入具有 PostCSS 支持的 Expo 超类。
const { FileStore } = require('@expo/metro-config/file-store');

config.cacheStores = [
  new FileStore({
    root: '/path/to/custom/cache',
  }),
];

module.exports = config;

请确保你没有在 metro.config.js 中禁用 CSS：

metro.config.js

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // 使用 Tailwind 时，不要禁用 CSS 支持。
  isCSSEnabled: true,
});