雲里
里雾

NativeWind v4 Expo 配置指南

nativewind 开发 更新于 2026/4/13

本页给出在 Expo SDK 54 项目中接入 NativeWind v4 所需的三个配置文件（tailwind.config.js、babel.config.js、metro.config.js）的完整写法，并说明 Tailwind CSS 必须锁定在 v3 的原因和常见排查路径。

为什么需要手动创建配置文件

Expo SDK 54 的默认脚手架不会自动生成 tailwind.config.js、babel.config.js、metro.config.js 这三个文件——因为 Expo 默认用自己托管的构建配置,这些文件只有在你需要自定义时才创建。NativeWind v4 需要深入 Babel 编译链和 Metro bundler,所以三个文件都要手动建。

三个配置文件详解

1. tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // NativeWind v4 提供的 preset,包含 RN 专属的 class 适配层
  presets: [require('nativewind/preset')],
  content: [
    './app/**/*.{js,jsx,ts,tsx}',
    './src/**/*.{js,jsx,ts,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

content 路径是最容易出错的地方:Tailwind 在构建时扫描这些文件,提取用到的 class 名生成最终 CSS。如果某个目录没有被 content 覆盖,该目录下组件用的 className 会被 Tailwind 当作”未使用”而裁剪掉——结果是样式静默失效,不报错,很难排查。

2. babel.config.js

module.exports = function (api) {
  api.cache(true)
  return {
    presets: [
      [
        'babel-preset-expo',
        {
          // 告诉 Babel 用 nativewind 的 JSX runtime 处理 className prop
          // 没有这行,className 在 RN 组件上会被忽略
          jsxImportSource: 'nativewind',
        },
      ],
      // 必须在 babel-preset-expo 之后
      'nativewind/babel',
    ],
  }
}

jsxImportSource: 'nativewind' 的作用:让 Babel 在编译 JSX 时注入 NativeWind 的 JSX transform,把 className prop 转换成 RN 可以理解的样式对象。没有这行,className="flex-1 bg-red-500" 会被当作普通字符串属性,在 RN 里无效。

3. metro.config.js

const { getDefaultConfig } = require('expo/metro-config')
const { withNativeWind } = require('nativewind/metro')

const config = getDefaultConfig(__dirname)

// withNativeWind 包装 Metro 配置,添加 CSS 文件处理能力
// input 指向 global.css,Metro 会监听这个文件的变化
module.exports = withNativeWind(config, { input: './global.css' })

global.css 和 _layout.tsx

还需要创建 global.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

然后在根 layout 导入:

// app/_layout.tsx
import '../global.css'

这个 import 触发 Metro 处理 CSS 文件,NativeWind 的样式才会生效。

版本锁定:Tailwind CSS v3

NativeWind v4 只支持 Tailwind CSS v3,不兼容 Tailwind CSS v4。

Tailwind CSS v4 于 2025 年发布,架构有重大变化(不再需要 tailwind.config.js,改用 CSS 变量配置)。NativeWind v4 的底层实现绑定了 Tailwind v3 的 API,所以安装时必须明确指定版本:

pnpm add nativewind
pnpm add -D tailwindcss@3

不加 @3 的话 pnpm 会安装最新的 Tailwind v4,然后各种报错。

常见坑速查

现象根因解法
className 没效果但无报错content 路径漏了对应目录检查 tailwind.config.js 的 content 数组
样式改了没更新Metro 缓存pnpm start --reset-cache
JSX 报类型错误:className 不在 RN props 里缺少 NativeWind 的 TS 类型声明/// <reference types="nativewind/types" /> 加到 env.d.ts
Babel transform 不生效preset 顺序错误nativewind/babel 必须在 babel-preset-expo 之后
@tailwind 指令报错VS Code PostCSS 插件不认识安装 Tailwind CSS IntelliSense 插件即可

参见

参考

版本说明