Tamagui

React + React Native 高性能通用 UI 系统 —— 通过编译时优化实现跨平台设计系统的极致性能。

技术简介说明

Tamagui 是一个面向 React 和 React Native 的通用 UI 系统，由 Nate Wienert 创建并维护。它的核心定位是解决跨平台开发中的一个长期痛点：如何在不牺牲性能和代码质量的前提下，让 Web 和 Native 共享同一套设计系统与组件代码。

Tamagui 的独特之处在于它不仅仅是一个样式库或组件库，而是一个包含 优化编译器 的完整体系。编译器在构建阶段将组件样式转换为平台原生代码 —— Web 端生成原子化 CSS（atomic CSS），Native 端生成提升后的静态样式对象 —— 从而实现接近零运行时开销的性能表现。据官方测试，应用加载速度比传统 React Native UI 库快 30-40%，渲染时间可达 0.02ms，远低于常规方案的 0.063ms。

Tamagui 还提供了包含 80+ 组件的 UI Kit、Token 化设计系统、响应式媒体查询、主题系统以及动画集成，形成了从设计 Token 到最终渲染的完整链路。2025-2026 年，随着 v2 的发布，Tamagui 进一步引入了 headless 组件变体、CSS 渐变与多层阴影支持、以及基于信号粒度的响应式 hooks，逐步成为跨平台高性能 UI 的重要选择。

基本信息

快速上手

安装

使用官方脚手架快速初始化项目：

# 创建新 Tamagui 项目
npm create tamagui@latest
 
# 或在已有 Expo 项目中安装
npx expo install tamagui @tamagui/config @tamagui/babel-plugin

对于 Next.js + React Native 的跨平台项目，需额外安装对应 bundler 插件：

# Webpack (Next.js)
npm install @tamagui/next-plugin
 
# Vite
npm install @tamagui/vite-plugin
 
# Metro (React Native / Expo)
npm install @tamagui/babel-plugin

基础配置

1. 创建设计系统配置文件（tamagui.config.ts）：

import { createTamagui } from 'tamagui'
import { defaultTheme } from '@tamagui/config/v3'
 
const tamaguiConfig = createTamagui({
  tokens: {
    size: { '$1': 4, '$2': 8, '$3': 12, '$4': 16 },
    space: { '$1': 4, '$2': 8, '$3': 12, '$4': 16 },
    color: {
      '$primary': '#007AFF',
      '$background': '#FFFFFF',
      '$color': '#000000',
    },
  },
  media: {
    xs: { maxWidth: 660 },
    sm: { maxWidth: 800 },
    md: { maxWidth: 1020 },
    lg: { maxWidth: 1280 },
  },
  shorthands: {
    p: 'padding',
    m: 'margin',
    fw: 'flexWrap',
    ai: 'alignItems',
    jc: 'justifyContent',
  },
  themes: [defaultTheme],
})
 
export type TamaguiConfig = typeof tamaguiConfig
declare module 'tamagui' {
  interface TamaguiCustomConfig extends TamaguiConfig {}
}
 
export default tamaguiConfig

2. 配置 Babel 插件（babel.config.js）：

module.exports = {
  presets: ['babel-preset-expo'],
  plugins: [
    [
      '@tamagui/babel-plugin',
      {
        components: ['tamagui'],
        config: './tamagui.config.ts',
      },
    ],
  ],
}

3. 添加 Provider 包裹根组件：

import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from './tamagui.config'
 
export default function App() {
  return (
    <TamaguiProvider config={tamaguiConfig}>
      <YourApp />
    </TamaguiProvider>
  )
}

最小示例

import { XStack, YStack, Text, Button, Card } from 'tamagui'
 
export function DemoScreen() {
  return (
    <YStack flex={1} padding="$4" space="$3" alignItems="center" justifyContent="center">
      <Card padding="$4" borderRadius="$4">
        <XStack space="$3" alignItems="center">
          <Text fontSize="$6" fontWeight="bold">
            Hello Tamagui
          </Text>
        </XStack>
        <Text color="$colorSecondary" marginTop="$2">
          跨平台高性能 UI
        </Text>
      </Card>
 
      <Button theme="active" size="$4" onPress={() => console.log('pressed')}>
        <Button.Text>点击我</Button.Text>
      </Button>
    </YStack>
  )
}

核心概念与架构

整体架构

Tamagui 的架构分为四层：

┌─────────────────────────────────────────────┐
│  UI Kit（80+ 跨平台组件）                    │
│  Stacks / Text / Forms / Menus / Panels ... │
├─────────────────────────────────────────────┤
│  设计系统层                                   │
│  Tokens / Themes / Media Queries / Shorthands│
├─────────────────────────────────────────────┤
│  核心样式引擎（@tamagui/core）               │
│  styled() / getStyles / useMedia / useTheme  │
├─────────────────────────────────────────────┤
│  优化编译器（@tamagui/static）               │
│  部分求值 / 静态提取 / 树扁平化 / 代码消除   │
│  输出 → Web: 原子化 CSS + HTML              │
│  输出 → Native: 提升的静态样式对象            │
└─────────────────────────────────────────────┘

编译器工作原理

Tamagui 编译器（@tamagui/static）是其性能优势的核心来源。编译过程包含四个关键步骤：

1. 部分求值（Partial Evaluation）：在构建时评估组件的样式表达式，将可静态确定的值提前计算。
2. 静态提取与提升（Static Extraction & Hoisting）：将样式从运行时内联表达式中提取出来，转为编译时常量。
3. 代码消除（Code Elimination）：移除运行时不再需要的样式计算逻辑和中间层。
4. 树扁平化（Tree Flattening）：将多层嵌套的 styled 组件层级"拍平"为单个平台原生元素（如 Web 的 <div> 或 <p>），大幅减少运行时渲染树深度。

编译器通过 tamagui.build.ts 作为单一配置源，Webpack、Vite、Next.js、Babel、Metro 等各个 bundler 插件自动共享同一配置。

核心布局原语

• XStack：水平 Flex 布局容器（flexDirection: 'row'）
• YStack：垂直 Flex 布局容器（flexDirection: 'column'）
• ZStack：层叠布局容器（position: 'absolute' 叠加）

Token 系统

设计 Token 在编译时被映射为 CSS 变量（Web）或原生样式常量（Native），实现类型安全的设计约束。Token 支持响应式覆盖，配合 useMedia hook 或 useTheme hook 实现动态切换。

核心特性

1. 编译时优化（零运行时开销）

编译器将样式在构建阶段完全解析，Web 端输出原子化 CSS，Native 端输出静态样式对象。运行时 JS 线程开销仅约 1ms，接近手写原生代码的性能（5% 以内）。

2. 跨平台 100% 代码共享

同一套组件代码可在 React Web（Next.js、Vite 等）和 React Native（Expo、裸 RN 项目）上运行，无需平台分支代码。Web 端输出原生 HTML + 原子 CSS，而非依赖 React Native Web 模拟。

3. Token 化设计系统

通过 createTamagui 定义类型安全的 Token 体系（尺寸、间距、颜色、圆角、 zIndex 等），所有组件通过 Token 引用样式值，确保全局设计一致性。支持多主题切换（内置 B/W、Ocean、SUPER、Cactus、Neon 等预设主题）。

4. 80+ 可组合 UI 组件

覆盖 Stacks、Headings、Text、Forms、Menus、Panels、Dialogs、Popovers、Toast、Context Menus 等常见 UI 场景。组件支持组合式 API（如 Button.Text），可选择有样式默认版本或 headless 无样式版本。

5. 响应式媒体查询

内置 useMedia hook 和组件级响应式 props，编译器可将 useMedia 和 useTheme 调用转换为 CSS 媒体查询和 CSS 变量，避免运行时重渲染。

6. 动画系统集成

v2 引入了 Motion 和 Reanimated 集成，支持精确控制进入/退出过渡动画，可在 Web 和 Native 上使用统一的动画 API。

7. Headless 组件变体

提供 headless（无样式）组件版本，仅暴露逻辑 hooks 和可访问性属性，允许开发者完全自定义视觉样式，同时获得交互逻辑和无障碍支持。

8. 类型安全的全链路

从 Token 定义到组件 Props，全程 TypeScript 类型推导。Token 名称、主题色、断点等均获得编辑器自动补全和类型检查支持。

9. CLI 工具链

@tamagui/cli 提供组件预编译、CSS 导出、AI 友好文档生成等能力，支持 --target（web/native）、--output、--expect-optimizations（CI 集成）等选项。

10. 渐进式主题与信号式响应

v2 引入 avoidReRenders 设置，将部分样式计算移出 React 生命周期，实现信号（Signal）级别的粒度控制，进一步减少不必要的重渲染。

生态图

Tamagui 生态
├── 核心层
│   ├── tamagui             — 主包（UI Kit + 核心样式引擎）
│   ├── @tamagui/core       — 基础样式库（View, Text, styled）
│   ├── @tamagui/static     — 优化编译器
│   └── @tamagui/config     — 预设配置（v3 preset）
│
├── Bundler 集成
│   ├── @tamagui/babel-plugin  — Babel / Metro 插件
│   ├── @tamagui/next-plugin   — Next.js 集成
│   ├── @tamagui/vite-plugin   — Vite 集成
│   └── tamagui-loader         — Webpack loader
│
├── UI 组件生态
│   ├── @tamagui/forms         — 表单组件
│   ├── @tamagui/menu          — 菜单 / 下拉菜单 / 上下文菜单
│   ├── @tamagui/dialog        — 对话框 / 弹窗
│   ├── @tamagui/popover       — 弹出层
│   ├── @tamagui/toast         — Toast 通知
│   ├── @tamagui/tooltip       — 工具提示
│   ├── @tamagui/tabs          — 标签页
│   ├── @tamagui/select        — 选择器
│   ├── @tamagui/sheet         — 底部抽屉
│   ├── @tamagui/progress      — 进度条
│   ├── @tamagui/slider        — 滑块
│   ├── @tamagui/switch        — 开关
│   ├── @tamagui/input         — 输入框（v2 重写）
│   └── @tamagui/image         — 图片（v2 重写）
│
├── 动画与交互
│   ├── @tamagui/animations-motion    — Motion 动画集成
│   ├── @tamagui/animations-reanimated — Reanimated 集成
│   └── @tamagui/animations-css        — CSS 动画
│
├── 工具链
│   ├── @tamagui/cli              — CLI 工具（预编译、CSS 导出等）
│   └── @tamagui/react-native-svg — 跨平台 SVG 支持
│
├── 框架层
│   ├── one（One Stack）    — 全栈通用应用框架
│   └── zero                — 本地优先数据层
│
└── 启动模板
    └── create-tamagui      — 脚手架工具（npm create tamagui@latest）

适用场景

1. 跨平台统一设计系统

需要 Web（Next.js / Vite）和移动端（React Native / Expo）共享完全一致的设计语言、组件和交互行为时，Tamagui 是最成熟的方案之一。一套代码、一套 Token、一套主题，编译时自动适配各平台。

2. 高性能要求的应用

对滚动流畅度、动画响应速度有严格要求的应用（如电商、社交、内容消费类 App），Tamagui 的编译器优化可将运行时开销降至接近原生水平，JS 线程开销仅约 1ms。

3. 大型设计系统构建

需要集中管理颜色、间距、字体等设计 Token，并确保数百个组件和页面一致性的团队。Tamagui 的类型安全 Token 系统 + 主题切换能力（支持暗色模式、品牌定制主题）非常适合中大型团队。

4. 需要自定义 UI 的产品

与 React Native Paper、React Native Elements 等预设风格库不同，Tamagui 支持从完全自定义的设计系统出发构建组件，headless 变体让开发者控制每一处视觉细节。

5. Next.js + React Native 共享组件库

团队同时维护 Next.js Web 应用和 React Native 移动应用，希望共享业务组件和 UI 层代码。Tamagui 的跨平台渲染能力（Web 输出原生 HTML + 原子 CSS，不依赖 React Native Web 完整模拟）是其核心差异化优势。

6. 本地优先 / 离线应用

配合 One Stack 框架和 Zero 数据层，Tamagui 可用于构建本地优先、离线可用的现代应用，UI 层与数据层形成完整解决方案。

7. 快速原型到生产的全流程

通过 create-tamagui 脚手架快速启动项目，内置 80+ 组件覆盖常见 UI 场景，从原型验证平滑过渡到生产环境，无需中途更换 UI 框架。

开发与工程化

开发环境要求

• Node.js：18+
• TypeScript：5.0+（v2 强制要求）
• React：19+（v2 要求）
• React Native：0.81+（v2 要求）
• Expo：推荐 SDK 52+
• Next.js：14+（Web 端）

构建与 Bundler 支持

Tamagui 通过 tamagui.build.ts 作为统一的编译配置入口，各 bundler 插件自动加载此配置：

CLI 工作流

# 预编译组件（生产优化）
tamagui --target web --output ./dist-optimized
 
# 生成平台特定文件 alongside 原文件
tamagui --output-around
 
# CI 验证优化是否生效
tamagui --expect-optimizations 10
 
# 导出设计系统 CSS
tamagui --export-css
 
# 预览优化效果（不修改文件）
tamagui --dry-run

测试策略

• 编译器输出可通过 --dry-run 和 --expect-optimizations 在 CI 中验证
• 组件测试可使用标准 React Testing Library（Web）或 React Native Testing Library
• 跨平台组件建议分别针对 Web 和 Native 目标运行测试套件

Monorepo 支持

Tamagui 天然支持 monorepo 架构，可通过 tamagui.build.ts 配置 packages 字段指定需要编译的包路径，配合 Turborepo 或 Nx 使用效果更佳。

性能与安全

性能特性

性能优化机制：

• 编译时静态提取：样式在构建阶段被提取为常量，运行时不做样式计算
• 原子化 CSS：Web 端生成最小化、可复用的原子 CSS 类，避免样式膨胀
• 树扁平化：多层 styled 组件在编译时被合并为单个原生元素
• avoidReRenders：将样式计算移出 React 渲染周期，减少不必要重渲染
• 浮动元素作用域：复杂列表和数据表中的浮层组件通过作用域隔离大幅降低渲染成本

安全考虑

• 作为纯 UI 层库，Tamagui 本身不直接处理网络请求或用户数据，安全面较小
• Token 和主题值为静态配置，不存在运行时注入风险
• 需注意设计系统配置文件不要暴露敏感的品牌或业务信息到客户端 bundle
• 使用 @tamagui/cli 的 CSS 导出功能时，注意构建产物的访问控制

技术对比

与主流方案对比

选型建议

• 选 Tamagui：需要 Web + Native 完全共享、追求极致性能、构建企业级设计系统
• 选 NativeWind：团队已熟悉 Tailwind、以 Native 为主、追求低学习曲线
• 选 React Native Paper：需要 Material Design 风格、快速出原型、不需要自定义设计系统
• 选 Gluestack UI：需要完全自定义视觉、模块化组合、无障碍支持
• 选 twrnc：小型项目快速迭代、不想配置编译工具链

最佳实践

1. 设计 Token 先行

在编写任何组件之前，先定义完整的 Token 体系。Token 是设计系统的"单一事实来源"：

// tamagui.config.ts — 先定义 Token，再构建组件
const config = createTamagui({
  tokens: {
    // 使用数值阶梯，便于维护和扩展
    size: { '$1': 4, '$2': 8, '$3': 12, '$4': 16, '$5': 20, '$6': 24 },
    space: { '$1': 4, '$2': 8, '$3': 12, '$4': 16, '$5': 20, '$6': 24 },
    zIndex: { '$1': 100, '$2': 200, '$3': 300 },
    radius: { '$1': 4, '$2': 8, '$3': 12, '$full': 9999 },
  },
})

2. 使用 Shorthands 提升开发效率

定义常用属性的简写，减少样板代码：

shorthands: {
  p: 'padding',
  px: 'paddingHorizontal',
  py: 'paddingVertical',
  m: 'margin',
  ai: 'alignItems',
  jc: 'justifyContent',
  fd: 'flexDirection',
  w: 'width',
  h: 'height',
}
 
// 使用：<YStack px="$4" py="$2" ai="center">

3. 组合式组件优于大型单体组件

利用 Tamagui 的组合式 API 拆分组件逻辑：

// ✅ 好的做法：组合式
<Card>
  <Card.Header>
    <Text fontSize="$5" fontWeight="bold">标题</Text>
  </Card.Header>
  <Card.Background>
    <Image source={bgImage} />
  </Card.Background>
</Card>
 
// ❌ 避免：超大组件

4. 正确使用响应式 Props

// 使用媒体查询实现响应式布局
<XStack
  flexDirection="column"
  $md={{ flexDirection: 'row' }}  // md 断点以上改为水平排列
  padding="$3"
  $sm={{ padding: '$2' }}         // sm 断点以下缩小间距
>

5. 确保 PortalProvider 存在

忘记包裹 TamaguiProvider（特别是其中的 PortalProvider）是最常见的错误，会导致 Dialog、Popover、Toast 等浮层组件崩溃。

6. 利用 Headless 变体实现自定义设计

当默认样式不满足需求时，使用 headless 版本获取纯逻辑 hooks：

import { useDialog } from '@tamagui/dialog'
 
function CustomDialog() {
  const { open, close, isOpen } = useDialog()
  // 完全自定义渲染，但获得交互逻辑和无障碍支持
}

7. CI 中验证编译优化

# 确保编译优化在 CI 中正常工作
tamagui --expect-optimizations 10

8. v2 迁移注意事项

• 必须升级到 TypeScript 5+、React 19+、React Native 0.81+
• 旧 Stack 组件已移除，改用 View
• 可访问性属性改用 Web 标准（aria-label 等）
• 间距属性改用标准 CSS gap
• 媒体查询命名改为 kebab-case（v5）

技术局限与边界

已知局限

1. 配置复杂度高：初始配置涉及 tamagui.config.ts、Babel 插件、bundler 插件、Provider 包裹等多步设置，学习曲线陡峭。对于小项目来说"性价比"不高。

2. 编译器依赖 bundler 集成：编译器需要正确配置 Babel 插件和 bundler 插件才能生效。配置不当会导致运行时降级（无编译优化），性能优势无法体现。调试编译问题时排查路径较长。

3. Web 端 React Native Web 兼容性：Tamagui 提供了自己的轻量 Web 渲染层，但并非所有 React Native API 都能 100% 映射到 Web DOM。复杂手势、特定平台 API（如 LayoutAnimation）在 Web 端可能需要额外处理。

4. 社区生态仍在成长：相比 React Native Paper（13k+ stars）或 NativeWind，Tamagui 的社区规模（14.1k stars）虽然在增长，但第三方插件、教程和社区支持仍不如更成熟的方案丰富。

5. 版本迭代激进：v1 期间多次快速发布导致回归问题，v2 虽然重建了测试基础设施（覆盖五种框架），但从 v1 到 v2 的迁移仍需注意多项破坏性变更。

6. 单维护者风险：Tamagui 主要由 Nate Wienert 一人主导开发，虽然项目活跃，但核心维护者单一带来一定的可持续性风险。

7. v2 强制高版本依赖：v2 要求 TypeScript 5+、React 19+、React Native 0.81+，对于尚未升级的团队来说迁移成本较高。

8. 复杂动画需额外集成：虽然 v2 引入了 Motion 和 Reanimated 集成，但复杂的自定义动画场景仍需要在 Web 和 Native 端分别适配。

边界总结

学习资源

官方资源

• Tamagui 官网 — 文档、API 参考、指南
• Tamagui GitHub — 源码、Issues、示例
• Tamagui Blog — 版本公告、技术文章
• Tamagui UI Kit — 组件文档和交互示例
• 编译器安装指南 — 编译器配置详解
• v1 → v2 升级指南 — 迁移文档

视频教程

• Nate Wienert - Tamagui: A performant UI Kit for Web + Native — 创作者亲自讲解
• React Native Radio RNR 259 - Tamagui with Nate Wienert — 播客访谈
• Dev Tools FM #120 - Tamagui, One Stack, Zero, and Universal Apps — 生态全景讨论
• React Native Styling with Tamagui — 实战演示

技术文章

• Why Tamagui Is a Game-Changer for React Native App — 2025 年深度分析
• Tamagui for React Native: Create Faster Design Systems — LogRocket 入门指南
• How to Integrate Tamagui with React Native Expo — Expo 集成教程
• The Frontend Trilemma — 为什么需要编译器
• NativeWind vs Tamagui vs twrnc: RN Styling 2026 — 2026 年选型对比

社区

• Nate Wienert (Twitter/X) — 创作者动态
• Tamagui GitHub Discussions — 社区讨论
• Reddit r/reactnative — React Native 社区讨论

2026 年现状

版本状态

截至 2026 年 7 月，Tamagui 的最新稳定版本为 v2.4.1（最后提交日期 2026 年 7 月 4 日）。v2 于 2025 年底进入 RC 阶段，2026 年 2 月发布 v2.0.0 正式版，经过数月的迭代已趋于稳定。v1 分支仍保持维护（v1.144.3），但已不推荐新项目使用。

项目活跃度

• GitHub Stars：14.1k+，持续增长
• 最后提交：2026 年 7 月 4 日，保持高频更新
• 维护状态：活跃开发中，v2 的测试基础设施经过全面重建（覆盖五种测试框架），稳定性大幅提升

v2 关键里程碑

• 核心包体积缩减约 1/3
• 引入 headless 组件变体
• 新增 CSS 渐变、多层阴影、混合模式支持
• 重建 Input 和 Image 组件，支持标准 HTML 属性
• Motion 和 Reanimated 动画集成
• 下拉菜单和上下文菜单
• unstyled 方法支持完全自定义样式
• 统一的 backgroundImage 和 textShadow 跨平台支持
• 原生平台的菜单和 Toast 通知集成
• CLI 支持 CSS 导出和 AI 友好文档生成
• 轻量级 TypeScript Web 运行时（替代 React Native Web，改善 tree-shaking）

生态扩展

Tamagui 已从单一的样式库发展为包含 One Stack（全栈通用应用框架）和 Zero（本地优先数据层）的完整生态系统，定位从"UI 组件库"升级为"通用应用开发平台"。

社区趋势

在 2026 年的 React Native 生态中，Tamagui 被普遍认为是 性能天花板最高 的跨平台 UI 方案。在 PkgPulse、Gluestack 等对比评测中，Tamagui 在 JS 线程开销（~1ms）、Web 渲染性能（0.02ms）等指标上持续领先。但其较高的配置复杂度和学习曲线仍是主要的使用门槛。

对于 Web + React Native 深度共享的大型项目，Tamagui 在 2026 年依然是最具竞争力的选择；对于纯 Native 或小型项目，开发者可能更倾向于选择 NativeWind 或 twrnc 等更轻量的方案。