React Native 组件库横评：HeroUI Native、Paper、Tamagui 与 gluestack-ui

8月 10, 2026

AI 参与说明（Agent：Codex、Lorentz、Anscombe、Dirac）：本文根据各项目的官方文档、发布记录、许可证与公开包元数据辅助整理。版本与组件目录核验于 2026-08-10；组件、兼容矩阵和许可会变化，请在选型或升级当天重新核对文中的一手链接。本文不把项目方的“production-ready”宣传、GitHub star 或 npm 下载量当作独立的质量或市场份额结论。

React Native 组件库的选择，决定的不只是“按钮长什么样”。它还会影响主题 token 的组织方式、手势与动画依赖、Portal / 弹层行为、无障碍实现、构建链的复杂度，以及未来替换组件库的成本。

本文横向比较以下四个当前值得评估的路线：HeroUI Native（含 Pro）、React Native Paper、Tamagui 与 gluestack-ui。NativeBase 和 UI Kitten 放在“既有项目与观察对象”部分，而不是和新项目的默认候选混为一谈。

先说结论#

这不是一张“谁最好”的排行榜。对于一个典型业务 App，Material 能否接受、日期选择器和图表是否真的需要、是否要把组件源码掌握在自己手里，往往比“组件数量”更重要。

比较前先分清四件事#

1. “React Native 组件”不等于系统控件#

这些库多数以 React Native 的 View、Text、Pressable 等 Host Components 为基础，再组合样式、手势、动画和可访问性语义。它们不会把 JSX 自动换成 SwiftUI、UIKit 或 Jetpack Compose 控件。

因此，“Native”通常表示它运行在原生 App 中、使用 React Native 的平台渲染与原生能力；它不表示每个按钮都是操作系统自带按钮。React Native 从 React 元素到 Host View 的过程，可参见站内的架构说明与官方渲染管线。

2. UI kit、样式系统与源码生成器不是同一种产品#

它们也不替代路由、表单校验、服务端状态、鉴权或应用的领域架构。一个组件库最多是 UI 基础层，不应成为业务 feature 直接到处依赖的“总框架”。

3. Expo 新项目还有一个硬门槛：New Architecture#

Expo SDK 55 起只能运行 React Native New Architecture；选择 UI 库时必须同时检查其全部原生 peer dependency，而不是只看主包能否安装。Expo New Architecture 指南

例如，HeroUI Native 依赖 Reanimated 4；Reanimated 4 只支持 New Architecture，且它与 React Native、Worklets 的版本组合有明确边界。Reanimated 兼容矩阵 Tamagui v2 则在安装文档中直接要求 React Native 0.81+、New Architecture、React 19+ 和 TypeScript 5+。Tamagui 安装要求

无论最终选谁，先在目标 Expo SDK 中运行：

npx expo-doctor@latest
npx expo install --check

然后用 development build 和双端 release build 验证；不要只因 Expo Go 打开了一个 Demo，就认为生产组合可用。

2026-08-10 的候选快照#

HeroUI 的稳定 / beta 状态来自其Native 发布记录与Pro 发布记录；Paper 的 v5 / v6 状态应以官方 Releases为准；Tamagui 与 gluestack-ui 的版本和支持边界见其安装文档与 gluestack-ui v5 文档。

版本号只是一次快照。尤其不应把 beta、alpha 或“预览版样式依赖”写成稳定 API 承诺。

HeroUI Native：OSS 做基础，Pro 做有边界的增量#

HeroUI Native 是 React Native 组件库；其公开包为 heroui-native，付费扩展包为 heroui-native-pro。Pro 建立在 OSS 之上，使用同一个 HeroUINativeProvider，不是另一套平行 UI 运行时。

OSS 与 Pro 的组件覆盖#

下表按官网当前的组件目录入口计数，而非 npm export 数：复合组件、Provider、主题工具和内部辅助入口不会完全等于这里的数字。OSS 组件目录 Pro 组件目录

这套划分很适合“用 OSS 覆盖常规页面，按需用 Pro 购买复杂交互的工程时间”的策略。不要因为已安装 Pro，就默认把每一个业务控件都写成 Pro 依赖；日期、时区、图表、滚轮选择器和 Overlay 的测试面更大，应按真实需求引入。

技术底座与最小接入形态#

HeroUI Native 使用 React Native primitives、Uniwind / Tailwind CSS v4、Reanimated、Gesture Handler、Safe Area、SVG 等依赖。包声明 React 19+、React Native 0.81+；当前官方脚手架使用 Expo 57、React Native 0.86.2，这是一份推荐组合快照，不是 HeroUI 对所有 Expo SDK 的最低承诺。HeroUI Native Quick Start

对 Expo 项目，版本应优先由 Expo SDK 对齐，而不是手工把 Reanimated 或 Worklets 升到某个看似更高的版本。因为 Reanimated 4 与 New Architecture、Worklets 有严格兼容范围，错误组合通常会在原生构建或运行时暴露，而不是 TypeScript 编译期。

以下是已经按官方文档配置完 peer dependency 后的示意性根部结构；它不是完整安装教程：

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

import { Stack } from 'expo-router';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { HeroUINativeProvider } from 'heroui-native/provider';

export default function RootLayout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>
        <Stack />
      </HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

/* global.css */
@import 'tailwindcss';
@import 'uniwind';
@import 'heroui-native/styles';

/* 仅在安装 Native Pro 后添加。 */
@import 'heroui-native-pro/styles';
@source './node_modules/heroui-native-pro/lib';

heroui-native 1.0.8 起其 stylesheet 会自行注册 source，因此不必再为 OSS 手写旧的 @source；Pro 目前仍要求 source 配置。路径相对于 global.css，monorepo 或 pnpm hoisting 下务必在无缓存构建中检查样式是否实际被扫描到。HeroUI Native 1.0.8 说明 HeroUI Native Pro 安装

HeroUI Native 还提供 granular import。例如只使用按钮时从 heroui-native/button 导入，并全项目保持这种方式；只要混入一次根入口组件导入，就可能失去该体积优化。Provider 还可通过 provider-raw 减少 Toast / Portal 相关默认能力，但这是需要自己承担对应行为的优化，不是常规起点。Provider 文档

Pro 的授权与 CI 是技术约束，不只是采购问题#

Native Pro 的安装不是单纯从公共 registry 下载：本机先通过 CLI 登录，自动化构建使用仅存在于 CI / EAS secret 中的 token。典型流程如下：

npx heroui-pro@latest login
npx heroui-pro@latest install

在 EAS 中应把 CI token 保存为 HEROUI_AUTH_TOKEN secret，例如：

eas env:create --name HEROUI_AUTH_TOKEN --value <CI_TOKEN> --scope project --visibility secret

不要把它放进 EXPO_PUBLIC_*、源代码、日志或仓库。HEROUI_PERSONAL_TOKEN 用于本机身份，不能拿来替代 CI token。Yarn Berry PnP 目前不受该安装流程支持；pnpm / Bun 则需要允许 postinstall。正式上线前一定要做一次“无本地缓存、无人工登录”的 CI 构建演练。Native Pro 安装与 CI

许可也需要拆开理解：OSS 是 Apache-2.0；Pro 是商业授权。Native Pro 需要 Mobile Hero 或 Super Hero 权益，不能只凭“Pro”字样推断可用。Individual 许可仅对应一位具名开发者；Team 按能访问 Pro 资产的具名员工或承包商计 seat。最终 App 可以分发，但 Pro 源码、模板和设计资产不能被公开再分发。HeroUI Native LICENSE HeroUI Pro 条款 Native Pro licensing

HeroUI Native 的风险如何看#

它并非“不能用于生产”，但也不应被当作十年历史的严格 semver 库：官方 1.0.5、1.0.8 这类 patch release 都列出 Breaking Changes，Pro beta.8 也有破坏性调整。HeroUI Native 1.0.5 HeroUI Native 1.0.8 Pro beta.8

实际做法是：精确锁定版本（不要让 ^ 自动漂移）、每次升级阅读 release notes、在 iOS 与 Android 做截图和交互回归，并把 feature 对 Pro 的直接依赖收敛到应用自有的 src/ui/ 适配层。

适用：移动端产品、视觉与交互要求高、想快速获得日期时间与图表等复杂控件、团队愿意维护 Expo / Reanimated / Uniwind 组合。

不适用或需谨慎：必须最低维护风险、不能接受商业 beta、无法安全提供 CI token、或者要用同一渲染组件无差别覆盖 Expo Web。HeroUI Native 官方当前不建议用于 Expo Web；如果未来要做 Web，应把它作为单独的渲染实现来规划，而不是把 Native 组件直接移植过去。Quick Start

React Native Paper：最保守的 Material 组件基线#

React Native Paper 的核心价值是成熟的 Material Design 组件、主题系统与相对浅的接入面。当前稳定线是 5.15.3；6.0.0-alpha.0 仍是预发布，且包含 TextInput 重写、FAB API 调整和弃用 API 删除，不应成为新生产项目的默认版本。React Native Paper Releases

它适合表单、列表、设置、内容、工具与企业业务应用：常见的 Button、TextInput、Menu、Dialog、Snackbar、FAB、BottomNavigation 等组件成熟，Material 3 的 light / dark theme 与 React Navigation 也有官方整合路径。Getting started 与 React Navigation 的主题整合

适用：团队希望先做稳定业务页面，接受 Material 语言，且不想把样式编译器、商业授权下载或大量原生 peer 变成基础风险。

不适用：产品必须有高度定制的品牌语言，却又不愿投入覆盖层与设计系统；或首要需求就是一组已经封装好的复杂图表、日期 / 时间和定制化选取器。

Tamagui：当“共享 UI 源码”真的是硬需求#

Tamagui 不只是组件库。它把 typed styling、tokens、themes、可选的 static compiler、styled / unstyled primitives 与 UI kit 放在同一体系中，目标是让 React Native 与 React Web 可共享大量代码。Tamagui introduction

关键是“可选 compiler”：不用 compiler 也能运行，安装它是为了进一步做静态提取与优化；不要把它误解成所有 Tamagui 项目的运行前置条件。Tamagui compiler

适用：一个团队确实要长期维护 React Web 与 Expo / React Native 的同源设计系统，且有能力维护相关构建配置。Expo Router 有官方接入指南，但仍应以本项目的 workspace、Metro 和部署目标做验证。Tamagui Expo guide

不适用：当前只做移动端，又只是想快速做几张页面；此时它解决的问题可能并不存在，却会引入 token、compiler 与跨端 abstraction 的维护负担。

gluestack-ui v5：源码所有权高，维护责任也高#

gluestack-ui v5 的核心模型接近 shadcn：CLI 把组件代码加入项目，团队可以直接改，而不是只等待库维护者提供 API。它采用 Tailwind CSS v4，支持 NativeWind v5 或 Expo-only 的 Uniwind 路线。gluestack-ui v5 stable 公告

这个模型对“品牌要求极高且必须深改组件”的团队有吸引力，但它不是零成本的自由：一旦组件进入仓库，上游的 bug fix、无障碍修复、破坏性变更和安全升级都要由团队选择性合并与验证。

这些边界都可在 v5 安装说明、组件成熟度目录和 v5 升级指南中核对。

适用：要长期持有组件源码、设计系统团队能承诺维护、并且先完成目标 Expo / Android / iOS 的 PoC。

不适用：希望“装完就少维护”、依赖当前 Next.js 通用渲染、或核心需求正好落在仍标 alpha 的复杂组件。

既有项目与观察对象：NativeBase、UI Kitten#

NativeBase：迁移背景，而不是新基座#

NativeBase 并没有突然无法使用，但官方已经把新项目方向引向 gluestack-ui，并说明 gluestack-ui 是为改善 NativeBase v3 的性能与可维护性问题而重写的路线。对已有 NativeBase 项目，应以稳定维护、逐页迁移或继续观察为目标；新项目不应把它列为默认候选。NativeBase 文档 Road ahead with gluestack-ui

UI Kitten：正在现代化，但新架构线仍未 GA#

UI Kitten 稳定 dist-tag 仍是 5.3.1，但在 2026-08-07 已发布 6.0.0-beta.2，声明支持 React 19、React Native 0.81、Expo 54、ESM 与 New Architecture。这不是“已废弃”，但也不能把 beta 当成稳健的 Expo 新项目默认项；如果 Eva Design System 是硬需求，先用目标 SDK 做真机与无障碍 PoC，并等待 GA 状态更清晰。UI Kitten 官网 v6 beta Releases

四条主路线的横向比较#

用决策树缩小候选，再做 PoC#

flowchart TD
  A["开始选 React Native UI 基础层"] --> B{"是否必须长期复用 Web 与 Native 的组件源码？"}
  B -- "是" --> C["优先 Tamagui 2.x\n验证 compiler / Metro / Web 部署"]
  B -- "否" --> D{"是否接受 Material Design，且维护风险最优先？"}
  D -- "是" --> E["优先 React Native Paper 5.x"]
  D -- "否" --> F{"是否已有 HeroUI Native 权益，并需要日期 / 图表等高阶控件？"}
  F -- "是" --> G["HeroUI OSS 为主 + 按需 Pro\n精确锁 beta 与 CI token"]
  F -- "否" --> H{"是否必须把组件源码放进本仓库深改？"}
  H -- "是" --> I["gluestack-ui v5 PoC\n团队承担上游合并"]
  H -- "否" --> J["先以 Paper 为成熟基线\n再基于真实设计缺口选库"]

这个流程故意没有把“GitHub stars 多”或“组件目录更多”作为分支条件。UI 库最常见的失败不是少一个按钮，而是上线后才发现复杂 Select、输入法、弹层、无障碍、Android 返回键或主题升级不符合真实产品。

建议的 PoC：不要比较 Demo，要比较同一张真实页面#

对每个候选实现同一组最小页面，再在同一台代表性 iPhone 与中低端 Android 上比对：

1. 登录 / 注册表单：密码、错误提示、焦点恢复、软键盘避让、提交 loading。
2. 长列表详情：图片、筛选、空状态、滚动性能、深色模式。
3. 编辑页面：日期 / 时间、复杂选择器、校验、底部操作栏。
4. Overlay：Dialog、Popover、BottomSheet、Toast，以及 Android 返回键和原生 modal 叠加。
5. 无障碍：VoiceOver、TalkBack、Dynamic Type / 字体放大、Reduce Motion、RTL、键盘焦点与颜色对比。

验收时至少回答以下问题：

• Expo development build、iOS release、Android release 是否都能干净构建？
• 依赖升级后 expo-doctor 是否仍健康？
• 每个 Overlay 是否能恢复焦点、关闭后是否留下不可点区域？
• 动画、图表、日期时间在低端 Android、时区、Locale 和大字号下是否仍正确？
• Pro 包在没有本机缓存、没有交互登录的 EAS CI 中是否可重复安装？
• 包体、冷启动、滚动与内存是否在真实数据量下达标？

测试不应只靠 screenshot。截图回归适合发现 HeroUI 这类视觉 / token 变更；还需要自动化交互测试与真机人工无障碍测试。组件库提供 ARIA-style props、screen reader props 或主题 API，不等于产品已经通过 VoiceOver / TalkBack 验收。

落地架构：让 UI 库可替换#

不管选哪一个，建议 feature 不直接遍地导入第三方组件，而是建立应用自己的 UI 入口：

src/
├── features/
│   ├── orders/
│   └── profile/
├── ui/
│   ├── Button.tsx
│   ├── FormField.tsx
│   ├── DateInput.tsx
│   ├── AppDialog.tsx
│   └── charts/
├── design/
│   ├── tokens.ts
│   └── theme.ts
└── platform/
    ├── keyboard.ts
    └── accessibility.ts

这不是为了把每一个第三方 API 重新发明一遍，而是为了把最可能变的部位收口：Button 变体、字段错误呈现、Dialog 行为、日期值格式、图表数据适配与品牌 tokens。将来 HeroUI Pro beta、Material theme、Tamagui styled primitive 或 gluestack copied component 发生变化时，影响面才不会扩散到所有业务页面。

同一应用通常不要同时引入两套完整 UI kit。两个 Provider、Portal、theme、字体默认值、手势与 Overlay 体系会互相增加不可预测性。正确的组合更接近“一套主 UI 基础层 + 少量专用、经过评估的无头组件或平台能力”。

结合当前前提的建议#

如果移动端是近期目标，并且 HeroUI Native Pro 已经是现有资产，最务实的起点是：以 HeroUI Native OSS 1.0.8 覆盖基础控件，先对真正需要的 Pro 日期 / 图表 / 选择器做一个小范围 PoC；同时用 React Native Paper 5.x 完成同一张关键页面作为成熟基线。这样可以把“视觉交付收益”与“Pro beta / peer dependency 风险”用真实结果比较，而不是只听宣传。

只有当“Web 与 Native 共用同一套组件实现”是长期、明确且可验收的目标时，才应把 Tamagui 提到第一候选。若重视完全掌握组件源码，再看 gluestack-ui v5；它是把维护权交给团队，不是把维护工作消失。

参考资料#

• HeroUI Native Quick Start、组件目录、Provider、1.0.8 发布说明
• HeroUI Native Pro 组件目录、安装与 CI、Pro licensing、商业条款
• Expo New Architecture、Reanimated compatibility
• React Native Paper 官方仓库、发布记录、Getting started
• Tamagui introduction、安装要求、Expo guide、compiler
• gluestack-ui v5 stable、安装说明、组件目录、升级指南
• NativeBase 的迁移说明、UI Kitten v6 beta Releases