在 Expo React Native 项目中使用…

当项目明确使用 NativeWind v4 与 Tailwind CSS v3（Expo 应用）时，用于搭建/修复配置、className 互操作与主题化。

适用场景

解决思路

1. 先读取 package.json 与 lockfile、真实应用入口、Expo 配置、Babel 配置、Metro 配置、Tailwind 配置和 CSS 入口；区分 Expo Router 与经典入口，并考虑 src/app、monorepo 或自定义项目根目录。
2. 按 v4 协调配置的不变量执行：使用 nativewind@^4 与 tailwindcss@^3.4.17，原生 peer 依赖通过应用的 Expo SDK 解析。
3. 配置 nativewind/preset 与 content globs，确保覆盖所有完整工具类字符串的来源。
4. 使用一个 CSS 入口并采用 Tailwind v3 指令，同时连接到 Metro 的 withNativeWind input 和真实应用入口。
5. 在 Babel 的 presets 中加入 nativewind/babel，并在 babel-preset-expo 上设置 jsxImportSource: "nativewind"。
6. 添加 nativewind-env.d.ts 并引用 nativewind/types，且不要遮蔽该包/模块名。
7. 保留无关的 Metro wrappers、Babel 插件、config 插件和项目模块格式；不要整体替换可运行应用的配置，也不要安装第二套不兼容的 Reanimated/Worklets 栈。
8. 排错顺序：先验证解析后的依赖主版本与首个真实错误；缓存重置无法修复 Tailwind v4/v3 不匹配。
9. 用项目已安装的 Tailwind v3 CLI 编译 CSS 入口，检查 content globs、静态类字符串和 NativeWind preset。
10. 验证 CSS 文件、Metro input 与应用 import 指向同一文件；从它们的真实位置计算路径，包括 src/app/_layout.tsx。
11. 合并所需的 Babel/Metro 集成，然后用 npx expo start --clear 重启 Metro。
12. 在每个目标平台上测试明显的布局/文本/颜色改动，再测试失败组件；仅 web 渲染成功不能证明原生互操作。
13. 构建组件时使用字面量 variant maps，而不是动态拼接扫描器看不到的类名；拼接类字符串不保证最后冲突的工具类生效。
14. 仅在组件需要 remapProps 或 cssInterop 时使用第三方组件互操作；互操作只配置一次，不要每次渲染都配置。
15. 主题化使用 v4 的 colour-scheme 与 CSS-variable API。
16. 添加另一个 safe-area provider 前先检查现有 provider；Expo Router 通常提供根集成，独立原生根或 modal 边界可能需要自己的 provider；验证实际 insets、嵌套导航与旋转，而不是把 provider 数量当作通用规则。
17. 验证与报告：运行项目 typecheck 与 Expo 依赖检查，编译/打包实际目标，并在可用环境中检查原生/web 渲染；检查 dark mode、disabled/pressed 状态、字体缩放、safe areas 及受影响的第三方组件；报告解析后的依赖版本、改动文件与实际测试平台；静态配置检查不等于设备测试。

适用边界 · 注意事项

• 不适用于 NativeWind v5 或 Tailwind v4 配置（这是独立技术栈，不是这些文件的直接升级）。
• 不适用于通用 web Tailwind 配置。
• 不适用于未使用 nativewind major 4 与 tailwindcss major 3 的 Expo 项目。