解决 React Native Nativewind 中的 "Use process(css).then(cb)" 错误

兼容性问题 React Native Nativewind

问题描述

当在 React Native 项目中使用 Nativewind 配置 Tailwind CSS 时，许多开发者会遇到以下编译错误：

screens/HomeScreen.js: Use process(css).then(cb) to work with async plugins

此错误通常发生在使用类似以下代码时:

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

export default function HomeScreen() {
  return (
    <View>
      <Text className="text-red">HomeScreen</Text>
    </View>
  )
}

触发场景

• 使用 expo 或 react-native-cli 创建的项目
• 通过 npm 或 yarn 安装 Nativewind 和 Tailwind CSS
• 运行项目启动命令后立即出现此错误

根本原因

此错误由 Nativewind 与 Tailwind CSS 最新版本之间的兼容性问题导致：

• Nativewind 对 Tailwind CSS v3.3.3+ 版本存在兼容性缺陷
• 使用 ^3.3.2 版本号时包管理器会自动安装不兼容的新版本
• Tailwind CSS v3.3.3 改变了异步插件处理机制

解决方案

最佳实践：固定 Tailwind CSS 版本

关键步骤

通过锁定 Tailwind CSS 到 3.3.2 版本可解决此问题

npm 用户执行：

npm install --save-dev tailwindcss@3.3.2
npm install nativewind

yarn 用户执行：

yarn add --dev tailwindcss@3.3.2
yarn add nativewind

额外维护步骤

1. 修改 package.json

确保版本号锁定（移除 ^ 符号）：

{
  "devDependencies": {
    // 从
    "tailwindcss": "^3.3.2",
    // 改为
    "tailwindcss": "3.3.2"
  }
}

2. 重新构建依赖关系

若问题仍然存在，尝试完整清理后重新安装：

# 卸载现有包
npm uninstall nativewind tailwindcss

# 安装兼容版本
npm install --save-dev tailwindcss@3.3.2
npm install postcss@8.4.23 # 兼容的 PostCSS 版本
npm install nativewind

3. 重启开发服务器

执行命令后必须重启开发服务器：

npm start -- --reset-cache

其他注意事项

Firebase 用户特别提示

若同时使用 Firebase 且降级 Tailwind CSS 后问题依旧，尝试降低 Firebase 版本：

npm install firebase@9.22.2

字体文件命名警告

某些字体文件命名可能引发类似错误：

- ZenLoop-Regular.ttf # 大小写敏感错误
+ Zenloop-Regular.ttf # 正确的命名

不推荐方案

避免手动修改 process(css).then(cb) 相关代码：

• Nativewind 在 React Native 环境中应自动处理此过程
• 手动修改可能破坏 Nativewind 的核心工作机制

问题追踪

此问题已被 Nativewind 团队记录：

• GitHub Issue：#498
• 影响版本：Tailwind CSS v3.3.3+
• 预计在 Nativewind 后续版本中彻底解决

总结

1. 核心方案：安装固定版本 tailwindcss@3.3.2
2. 关键操作：在 package.json 中移除版本号前的 ^
3. 必要步骤：重新启动开发服务器并清理缓存
4. 避免操作：不要尝试手动实现 process(css) 逻辑

通过锁定 Tailwind CSS 版本，您的 Nativewind 配置将恢复正常工作，您可以在 React Native 中安全使用 className 属性实现样式管理。

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

// 正确配置后不再报错
export default function HomeScreen() {
  return (
    <View>
      <Text className="text-lg text-red-500">主页内容</Text>
    </View>
  )
}