styling-nativewind-v4-expo

Expo 中的 NativeWind v4

这是一个有意针对 v4 的技能。截至审查日期，官方站点将 v5 标记为预发布版；v5/Tailwind v4 配置属于独立技术栈，不能直接替换这些文件。编辑前请检查锁文件，并明确保留此技能所用依赖的主版本。

确认配置

读取 package.json 和锁文件、实际应用入口、Expo 配置、Babel 配置、Metro 配置、Tailwind 配置以及 CSS 入口。确认使用的是 Expo Router 还是经典入口，并考虑 src/app、monorepo 或自定义项目根目录。

请参阅 references/expo-setup.md，了解配套的 v4 设置。需满足以下条件：

• 使用 nativewind@^4 和 tailwindcss@^3.4.17；原生 peer 依赖通过应用的 Expo SDK 解析。
• 使用 nativewind/preset，并配置 content glob，涵盖所有完整工具类字符串的来源。
• 使用一个 CSS 入口，其中包含 Tailwind v3 指令，并将其同时接入 Metro 的 withNativeWind 输入和实际应用入口。
• 将 nativewind/babel 放在 Babel 预设中，并在 babel-preset-expo 上设置 jsxImportSource: "nativewind"。
• nativewind-env.d.ts 引用 nativewind/types，且不覆盖包名或模块名。

保留无关的 Metro 包装器、Babel 插件、配置插件和项目模块格式。不要彻底替换正常运行的应用配置，也不要安装第二套不兼容的 Reanimated/Worklets 技术栈。

按有效顺序排查

1. 检查已解析的依赖主版本和最先出现的实际错误；清除缓存无法修复 Tailwind v4/v3 不匹配。
2. 使用项目已安装的 Tailwind v3 CLI 编译 CSS 入口。检查 content glob、静态类名字符串和 NativeWind preset。
3. 确认 CSS 文件、Metro 输入和应用导入指向同一个文件。根据它们的实际位置计算路径，包括 src/app/_layout.tsx。
4. 合并所需的 Babel/Metro 集成，然后运行 npx expo start --clear 重启 Metro。
5. 在每个目标平台上测试明显的布局、文本或颜色变化，然后测试出问题的组件。仅 Web 渲染成功并不能证明原生互操作正常。

如需进一步排查，请参阅 references/troubleshooting.md。应从此技能所在目录（而非应用目录）解析捆绑的参考文件路径。

构建组件

使用字面量变体映射，而不是动态构造扫描器无法识别的类名。references/patterns.md 介绍了类型化组件、明确的覆盖语义以及可访问的 Pressable 内容。拼接类名字符串并不能保证最后一个冲突工具类生效。

只有当组件需要 remapProps 或 cssInterop 时，才使用 references/third-party-components.md；互操作配置应只执行一次，而不是每次渲染时执行。v4 的配色方案和 CSS 变量 API 请参阅 references/theming-dark-mode.md。

添加另一个安全区 Provider 前，先检查现有配置。Expo Router 通常会提供根级集成；独立原生根节点或模态边界可能需要各自的 Provider。请验证实际安全区内边距、嵌套导航和屏幕旋转，而不要将 Provider 数量视为适用于所有场景的规则。

验证并报告

运行项目的类型检查和 Expo 依赖检查，编译或打包实际目标，并在环境可用时检查原生/Web 渲染。检查深色模式、禁用/按下状态、字体缩放、安全区以及受更改影响的第三方组件。报告已解析的依赖版本、修改的文件和实际测试的平台；静态检查配置不等于设备测试。

来源

根据 NativeWind 安装指南和自定义组件于 2026-09-13 审查。对于可选的冲突合并，tailwind-merge 明确建议 Tailwind v3 用户使用其 v2.6.0 系列。