gluestack-ui

面向 React Native 与 Expo 的跨端 UI 组件库，基于 Tailwind CSS (NativeWind) 构建，采用 copy-paste 架构模式。

技术简介说明

gluestack-ui 是由 GeekyAnts 团队开发的跨平台 UI 组件库，定位为 NativeBase 的继任者。它提供了一套可复制粘贴的 UI 组件，使用 Tailwind CSS 和 NativeWind 作为样式引擎，支持在 React Native 和 Expo 项目中快速构建一致、可访问且高性能的用户界面。

该项目最初作为 NativeBase 的全面重构而诞生，解决了 NativeBase 在性能、可维护性和包体积方面的三大痛点。gluestack-ui 采用"无样式架构"（unstyled architecture），将组件的逻辑与样式彻底解耦，开发者可以自由选择样式方案，实现真正的无限定制。

经过多个版本的迭代演进（v1 → v2 → v3 → v4 → v5），gluestack-ui 在 v5 版本中做出了重大架构决策——完全聚焦于 React Native 和 Expo 原生平台，放弃了 Next.js/Web 端支持，以换取更极致的原生性能和开发体验。这一决策使其成为专注移动端的、深度集成 NativeWind v5 和 Expo Router 的组件解决方案。

基本信息

• 官网：https://gluestack.io
• GitHub：https://github.com/gluestack/gluestack-ui
• License：MIT License
• 最新版本：v5.0.0（2026 年 6 月 25 日稳定发布）
• 主要维护者/公司：GeekyAnts（印度班加罗尔，React Native 咨询公司，2015 年起深耕 RN 领域，服务 200+ 客户）
• GitHub Stars：5.2k+
• GitHub Forks：225+
• 总提交数：16,564+
• 总发布数：610+
• 主要语言：TypeScript (71.9%)、MDX (23.7%)

快速上手

安装

前提条件：

• Expo SDK 50 或更高版本
• Node.js 环境
• Windows 支持不完整，建议使用 macOS 或 Linux

初始化项目：

# 在已有 Expo 项目中初始化
npx gluestack-ui@latest init
 
# Monorepo 场景指定路径
npx gluestack-ui init --monorepo --path packages/ui --nativewind-v5 -y
 
# CI 环境跳过交互提示
npx gluestack-ui init -y

初始化命令会完成以下操作：

1. 生成 gluestack-ui.config.json 配置文件
2. 注入 Provider 包装组件
3. 安装基础组件（Toast、Icons 等）
4. 更新样式和打包脚本配置

添加组件：

# 添加单个组件
npx gluestack-ui@latest add button
 
# 添加多个组件
npx gluestack-ui@latest add button alert-dialog modal
 
# 添加全部组件
npx gluestack-ui@latest add --all

升级版本：

# 升级到 NativeWind v5 / Tailwind v4
npx gluestack-ui@latest upgrade

基础配置

初始化后会生成 gluestack-ui.config.json 配置文件，核心配置项包括：

{
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "global.css"
  },
  "app": {
    "entry": "app/_layout.tsx",
    "provider": "components/ui/provider"
  },
  "components": {
    "path": "components/ui"
  }
}

Monorepo 配置： 仅需定义共享文件夹路径，CLI 会自动处理跨包引用。

最小示例

// components/ui/provider.tsx
import { GluestackUIProvider } from '@gluestack-ui/provider'
import { config } from './gluestack-ui.config'
 
export function Provider({ children }: { children: React.ReactNode }) {
  return (
    <GluestackUIProvider config={config}>
      {children}
    </GluestackUIProvider>
  )
}
 
// app/_layout.tsx
import { Provider } from '@/components/ui/provider'
import { Button, ButtonText } from '@/components/ui/button'
 
export default function RootLayout() {
  return (
    <Provider>
      <Button onPress={() => console.log('pressed')}>
        <ButtonText>Hello gluestack-ui</ButtonText>
      </Button>
    </Provider>
  )
}

核心概念与架构

Copy-Paste 架构

gluestack-ui v5 的核心设计理念是 copy-paste 架构：组件不是作为预打包的 npm 依赖引入，而是直接复制到你的项目源码中。这意味着：

• 你拥有组件的完整源码控制权
• 可以按需修改任何组件的内部实现
• 不受上游组件 API 变更的被动影响
• 实现真正的"无限定制"

无样式层（Unstyled Architecture）

组件逻辑与样式完全解耦：

• Headless 模式：组件只提供交互逻辑和无障碍支持，不带任何默认样式
• NativeWind 驱动：样式完全通过 Tailwind CSS 类名定义
• 主题令牌（Theming Tokens）：通过配置令牌实现全局一致的样式定制

三层架构

┌─────────────────────────────────────┐
│          应用层（你的代码）            │
├─────────────────────────────────────┤
│     gluestack-ui 组件（copy-paste）   │
│     - 交互逻辑                        │
│     - 无障碍支持                       │
│     - 状态管理                        │
├─────────────────────────────────────┤
│     NativeWind v5 / Tailwind v4      │
│     - 样式引擎                        │
│     - 主题令牌                        │
├─────────────────────────────────────┤
│     React Native / Expo              │
│     - 原生渲染                        │
│     - Expo Router                     │
└─────────────────────────────────────┘

MCP Server 集成

gluestack-ui 提供 MCP（Model Context Protocol）服务器，AI 助手可以通过 MCP 协议直接访问类型安全的组件，加速开发工作流。

核心特性

• Copy-Paste 架构：组件直接复制到项目中，拥有完整源码控制权，支持无限定制，不存在黑盒依赖
• NativeWind v5 / Tailwind v4 集成：深度集成 Tailwind CSS 样式引擎，支持 utility-first 开发模式，跨组件样式一致性
• 无样式架构（Unstyled）：组件逻辑与样式解耦，提供 headless 原语，开发者自由选择样式方案
• Expo Router 深度集成：一等公民级别的 Expo Router 支持，开箱即用的路由集成体验
• 模块化按需引入：只添加需要的组件，零冗余，不引入未使用的代码，优化包体积
• 无障碍访问（Accessibility）：内置 WAI-ARIA 规范支持、键盘导航、屏幕阅读器兼容，确保应用包容性
• 灵活主题系统：通过 theming tokens 和配置实现全局主题切换、深色模式支持
• TypeScript 严格类型：全部使用 TypeScript 编写，提供完整的类型推导和编辑器智能提示
• CLI 工具链：gluestack-ui CLI 支持项目初始化、组件添加、版本升级等全流程自动化
• Agent Skills 支持：可通过 npx skills add 安装 AI agent 技能包，与 AI 辅助开发深度整合

生态图

核心包生态

关键依赖

• NativeWind v5：React Native 上的 Tailwind CSS 实现，核心样式引擎
• Tailwind CSS v4：utility-first CSS 框架
• Expo Router：基于文件系统的路由方案
• Expo SDK 50+：底层运行时环境
• React Native：跨平台原生渲染框架

相关工具与扩展

• gluestack-ui CLI：项目脚手架、组件管理、版本升级
• gluestack-ui MCP Server：AI 辅助开发集成
• gluestack agent-skills：AI Agent 技能包（npx skills add gluestack/agent-skills --skill gluestack-ui-v5）
• ui-examples：官方示例仓库（https://github.com/gluestack/ui-examples）
• starter-kits：项目启动模板

社区生态

• Discord 社区（官方支持渠道）
• GitHub Discussions（技术讨论、RFC、版本规划）
• Twitter/X（@gluestack）
• LinkedIn 官方页面
• YouTube 教程频道
• Stack Overflow 标签问答

适用场景

• Expo / React Native 移动端应用开发（最核心场景） 基于 NativeWind v5 和 Expo Router 深度集成，是 Expo 项目的最佳搭档，提供一致的组件开发体验

• 跨平台 UI 统一设计系统 在 iOS 和 Android 上保持统一的组件外观和交互行为，适合需要品牌一致性的产品

• 从 NativeBase 迁移的项目 作为 NativeBase 的官方继任者，提供 @gluestack-ui/themed-native-base 适配包，平滑迁移路径

• 需要高度定制的组件库 copy-paste 架构让开发者拥有组件源码的完全控制权，适合对 UI 有严格要求的设计系统

• 无障碍要求严格的企业应用 内置 WAI-ARIA 规范和键盘导航支持，满足企业级无障碍合规需求

• AI 辅助开发工作流 通过 MCP Server 和 Agent Skills，与 Claude Code 等 AI 工具深度集成，加速组件开发

• Monorepo 项目结构 CLI 原生支持 monorepo 模式，适合多包共享 UI 组件的大型项目

开发与工程化

开发流程

1. 项目初始化：使用 npx gluestack-ui@latest init 搭建基础架构
2. 组件添加：通过 CLI 按需添加组件到项目中
3. 定制主题：修改 theming tokens 和 Tailwind 配置
4. 组件开发：基于 copy-paste 的组件源码进行二次开发
5. 类型检查：全量 TypeScript 支持，确保类型安全

构建部署

• gluestack-ui 组件直接编译到你的 Expo/React Native 项目中
• 无额外的构建步骤，组件作为源码参与项目打包
• 通过 NativeWind 的 PostCSS 插件处理 Tailwind 类名
• 使用 Expo 的标准构建流程（eas build 或 expo build）

CI/CD 集成

# CI 环境非交互式初始化
npx gluestack-ui init -y
 
# Monorepo CI 配置
npx gluestack-ui init --monorepo --path packages/ui --nativewind-v5 -y
 
# 锁版本确保可复现构建
npx [email protected] add button

Monorepo 最佳实践

• 将 gluestack-ui 组件放在共享包中（如 packages/ui/）
• 使用 --path 参数指定组件输出目录
• 通过 gluestack-ui.config.json 统一管理配置
• 各应用包通过路径引用共享组件

性能与安全

性能特点

• 原生性能优先：v5 完全围绕原生性能设计，消除不必要的 JS 层开销
• 按需加载：只引入使用的组件，零冗余代码
• NativeWind v5 编译优化：Tailwind 类名在编译时处理，运行时开销极小
• 主题令牌解析开销：styled 层的主题令牌解析会在每次渲染时产生少量 JS 开销，但对典型 UI 页面影响可忽略

优化建议

• 优先使用 headless 模式，减少不必要的样式层开销
• 避免在高频更新组件上使用复杂的主题令牌链
• 利用 React Native 的 React.memo 和 useMemo 优化重渲染
• 使用 Expo 的 Hermes 引擎提升启动性能

安全注意事项

• 组件源码直接在项目中，可以完整审查所有代码
• 无远程代码执行风险（区别于某些运行时 UI 框架）
• 定期更新依赖（NativeWind、Expo SDK）以获取安全补丁
• 注意 gluestack-ui.config.json 中路径配置的安全性，避免暴露敏感路径

已知性能边界

• 主题令牌解析在极端场景下（超大量组件同时渲染）可能产生可测量的 JS 开销
• NativeWind 的样式编译在大型项目中可能增加构建时间
• adapter 包已在 v5 中移除，跨平台适配需要额外处理

技术对比

与同类 React Native UI 库对比

选择建议

选 gluestack-ui 如果你：

• 使用 Expo 作为主力开发框架
• 偏好 Tailwind CSS 的 utility-first 开发模式
• 需要组件源码的完全控制权（copy-paste）
• 从 NativeBase 迁移
• 不需要 Web 端支持

选 Tamagui 如果你：

• 需要同时支持 Web 和 Native
• 偏好全栈统一的 UI 解决方案
• 接受较高的学习成本换取更强的定制能力

选 React Native Paper 如果你：

• 需要 Material Design 3 合规
• 偏好开箱即用的完整组件目录
• 不需要 Web 端支持

选 Unistyles 如果你：

• 正在构建自己的组件库，需要优秀的样式基础设施
• 性能是首要考量
• 需要媒体查询和响应式样式支持

最佳实践

生产环境建议

1. 拥抱 copy-paste 模式：将组件视为"起点"而非"终点"，根据业务需求积极修改组件源码
2. 统一主题令牌：在 gluestack-ui.config.json 中集中管理设计令牌，避免硬编码样式值
3. 按需添加组件：只通过 CLI 添加实际使用的组件，避免 add --all 引入冗余代码
4. Expo Router 优先：充分利用 Expo Router 的深度集成，使用文件系统路由组织页面
5. 锁版本管理：在 CI/CD 中使用固定版本号（如 [email protected]）确保构建可复现

常见陷阱

• Windows 支持不完整：CLI 在 Windows 上可能存在问题，建议使用 WSL 或手动配置
• v5 不支持 Web：如果需要 Web 端，应使用 v4 或选择其他方案（如 Tamagui）
• NativeWind 版本绑定：v5 强绑定 NativeWind v5，不能与 v4 混用
• Expo SDK 版本要求：需要 SDK 50+，低版本需先升级
• adapter 包已移除：v5 不再有 adapter 包，跨平台适配方案需重新评估

推荐模式

// 推荐：使用 headless 组件 + 自定义样式
import { useButton } from '@gluestack-ui/button'
 
function CustomButton({ children, ...props }) {
  const { buttonProps, buttonTextProps } = useButton(props)
  return (
    <Pressable {...buttonProps} className="bg-primary-500 rounded-lg px-4 py-2">
      <Text {...buttonTextProps} className="text-white font-bold">
        {children}
      </Text>
    </Pressable>
  )
}

技术局限与边界

已知限制

• 不支持 Web 端：v5 完全移除了 Next.js/Web 支持，adapter 包已停止维护
• Windows 开发体验：CLI 工具在 Windows 上支持不完整，官方建议使用替代方案
• Expo 强绑定：深度依赖 Expo 生态，非 Expo 的 bare React Native 项目支持有限
• NativeWind 版本锁定：v5 仅支持 NativeWind v5，无法兼容旧版本
• 组件数量相对有限：相比 React Native Paper 等成熟库，组件种类仍在增长中

不适用场景

• 跨端（Web + Mobile）统一项目：v5 已放弃 Web，需要跨端请选择 Tamagui 或 v4
• Material Design 严格要求：gluestack-ui 不绑定特定设计系统，MD 合规需用 React Native Paper
• bare React Native 项目（非 Expo）：gluestack-ui 优先支持 Expo 工作流
• 极致性能场景：虽然性能良好，但 Unistyles 的 C++ 原生方案在极端场景下更优
• 小型快速原型：copy-paste 模式需要一定的初始配置时间，快速原型可能更适合开箱即用的方案

迁移注意事项

• 从 NativeBase 迁移：使用 @gluestack-ui/themed-native-base 适配包，逐步替换
• 从 v3/v4 升级：参考官方 Migration Guide，注意 API 变更和配置格式变化
• 从 v4 到 v5：重大变更——Web 支持移除、adapter 包移除、NativeWind v5 必须升级
• 从其他库迁移：组件 API 设计差异较大，建议渐进式替换而非一次性迁移

学习资源

官方文档

• 官方文档首页：https://gluestack.io/ui/docs
• 快速开始指南：https://gluestack.io/ui/docs/home/getting-started/cli
• 组件文档：https://gluestack.io/ui/docs/home/components/（各组件独立页面）
• 升级指南：
  • 升级到 v2：https://gluestack.io/ui/docs/guides/more/upgrade-to-v2
  • 升级到 v3：https://gluestack.io/ui/docs/guides/more/upgrade-to-v3
  • 升级到 v4：https://v4.gluestack.io/ui/docs/guides/more/upgrade-to-v4
  • 升级到 v5：官网 Migration Guide 部分
• 版本发布记录：https://gluestack.io/ui/docs/guides/more/releases
• CLI 工具文档：https://gluestack.io/ui/docs/home/getting-started/cli

教程与视频

• YouTube 官方频道：贡献教程、项目搭建演示
• "React Native Expo + Gluestack Setup: Build a Threads Clone"（YouTube 实战教程）
• "Accelerate Your Universal App Development with gluestack-ui"（技术演讲）
• gluestack-ui Contribution Tutorial（YouTube 贡献指南）

社区资源

• GitHub Discussions：https://github.com/gluestack/gluestack-ui/discussions（RFC、技术讨论、版本规划）
• GitHub Issues：https://github.com/gluestack/gluestack-ui/issues（Bug 报告、功能请求）
• Discord 社区（官方支持渠道）
• Twitter/X：@gluestack
• LinkedIn：gluestackio
• Stack Overflow：gluestack-ui 标签
• Medium 博客：社区开发者经验分享

示例项目

• ui-examples：https://github.com/gluestack/ui-examples
• todo-example-app：https://github.com/gluestack/gluestack-ui-todo-example-app
• starter-kits：https://github.com/gluestack/gluestack-ui-head-starter-kits
• Next.js Page Router 模板：https://github.com/gluestack/gluestack-ui-nextjs-page-router-template（v4 及之前）

2026 年现状

最新版本

• 稳定版：v5.0.0（2026 年 6 月 25 日发布）
• 核心变更：完全聚焦 React Native/Expo 原生平台，移除 Web 支持，深度集成 NativeWind v5 和 Expo Router
• NPM 发布状态：活跃更新中

发展趋势

• 专注原生性能：v5 的架构决策表明团队选择"做好一件事"而非"覆盖所有平台"
• AI 集成深化：MCP Server 和 Agent Skills 的推出显示团队在 AI 辅助开发方向持续投入
• 版本迭代快速：从 v2 到 v5 仅用约两年时间，显示活跃的开发节奏
• 社区稳步增长：GitHub Stars 从 2024 年的约 3.9k 增长到 2026 年中的 5.2k

社区活跃度

• 代码活跃度：16,564+ 次提交，610+ 次发布，最近提交时间为 2026 年 5 月
• 问题响应：GitHub Issues 持续有新问题提交和回复
• 社区讨论：Discussions 活跃，包含 RFC 讨论（如 v2、v4、v5 的讨论帖）
• 生态扩展：starter-kits、examples、agent-skills 等周边仓库持续更新

未来路线图

• 持续完善 v5 组件生态，补齐更多组件
• 深化 AI Agent 集成（MCP Server 和 agent-skills）
• 优化 NativeWind v5 性能表现
• 强化 CLI 工具的跨平台支持（尤其是 Windows）
• NativeBase 企业版付费支持可能继续维护旧用户

风险评估

• Web 支持移除：对于需要跨端的项目是重大限制，需谨慎评估
• Expo 绑定：非 Expo 项目的适用性有限
• 版本迭代快：大版本间可能存在破坏性变更，升级成本需考量
• 社区规模中等：相比 React Native Paper 等库，遇到问题时可参考的资源相对较少