Arco Design

字节跳动企业级 React 组件库，60+ 精选组件，完整的设计开发生态系统

技术简介说明

Arco Design 是由字节跳动（ByteDance）内部设计团队开发并开源的企业级产品设计系统，提供从设计到开发的完整解决方案。它最初作为字节跳动内部的设计规范和组件库使用，经过飞书（Lark）等多款产品的验证后对外开源。

Arco Design 的定位不仅仅是组件库，而是一套完整的设计与开发解决方案，包括设计规范、React/Vue 组件库、Pro 中后台模板、Design Lab 主题平台、IconBox 图标管理和 Material 物料市场等生态工具。其设计理念强调"高效、灵活、一致"，旨在帮助团队快速搭建高质量的企业级产品。

在技术实现上，Arco Design React 版基于 TypeScript 构建，提供 60+ 开箱即用的组件，支持 Design Token 主题定制、按需加载和 SSR。截至 2026 年，项目在 GitHub 上拥有 5,600+ Star，最新版本 v2.66.15 持续维护中。

基本信息

• 官网：https://arco.design
• GitHub：https://github.com/arco-design/arco-design
• NPM：https://www.npmjs.com/package/@arco-design/web-react
• 主要维护者/公司：字节跳动（ByteDance）

快速上手

安装

# npm
npm install @arco-design/web-react
 
# yarn
yarn add @arco-design/web-react
 
# pnpm
pnpm add @arco-design/web-react

基础配置

引入组件样式：

// 全量引入
import '@arco-design/web-react/dist/css/arco.css'
 
// 或使用 less 变量方式引入（支持主题定制）
import '@arco-design/web-react/dist/css/index.less'

按需加载配置（Vite / Webpack 自动 tree-shaking，无需额外插件）：

// 直接按需引入组件即可，构建工具自动 tree-shaking
import { Button, Table } from '@arco-design/web-react'

最小示例

import React from 'react'
import { Button, Space, Message } from '@arco-design/web-react'
import '@arco-design/web-react/dist/css/arco.css'
 
function App() {
  const handleClick = () => {
    Message.info('欢迎使用 Arco Design!')
  }
 
  return (
    <Space direction="vertical" size="large">
      <h1>Hello Arco Design</h1>
      <Space>
        <Button type="primary" onClick={handleClick}>主要按钮</Button>
        <Button type="secondary">次要按钮</Button>
        <Button type="dashed">虚线按钮</Button>
      </Space>
    </Space>
  )
}
 
export default App

核心概念与架构

设计体系架构

Arco Design 不仅仅是一个组件库，而是一套完整的设计系统解决方案：

┌────────────────────────────────────────────┐
│              Arco Design 生态               │
├───────────────┬────────────────────────────┤
│  设计资源      │  @arco-design/design       │
│  设计规范      │  色彩/字体/间距/图标规范     │
├───────────────┼────────────────────────────┤
│  React 组件库  │  @arco-design/web-react    │
│  Vue 组件库    │  @arco-design/web-vue      │
│  移动端组件    │  @arco-design/mobile-react  │
├───────────────┼────────────────────────────┤
│  Design Lab   │  在线主题定制平台           │
│  IconBox      │  图标管理平台              │
│  Material     │  物料市场                  │
├───────────────┼────────────────────────────┤
│  Arco Pro     │  中后台前端解决方案         │
│  Arco CLI     │  脚手架与开发工具           │
└───────────────┴────────────────────────────┘

Design Token 体系

Arco Design 采用分层的设计令牌体系：

• 基础变量：色板、字号、间距、圆角等基础设计变量
• 语义变量：基于基础变量映射的语义化变量（如 color-primary、color-success）
• 组件变量：每个组件独立的样式变量，实现细粒度的主题定制

组件架构

┌──────────────────────────────────┐
│           应用层 (App)            │
├──────────────────────────────────┤
│      组件层 (Components)          │
│  基础 / 输入 / 展示 / 导航 / 反馈 │
├──────────────────────────────────┤
│      样式层 (Style System)        │
│  Design Tokens / Less 变量        │
├──────────────────────────────────┤
│      工具层 (Utilities)           │
│  @arco-design/design             │
└──────────────────────────────────┘

核心特性

• 60+ 精选组件：覆盖基础、输入、展示、导航、反馈五大品类，开箱即用
• Design Lab 主题平台：在线可视化主题定制工具，一键生成主题包
• 完整的 TypeScript 支持：所有组件均提供精确的类型定义
• 按需加载：自动 tree-shaking，无需额外 Babel 插件
• 国际化方案：内置 20+ 语言包，支持自定义扩展
• IconBox 图标平台：在线图标管理和批量导出工具
• Material 物料市场：社区共享的组件物料市场，支持自定义物料发布
• Arco Pro 解决方案：开箱即用的中后台前端模板，包含 16+ 页面模板
• 响应式设计：栅格系统支持响应式断点配置
• 无障碍支持：遵循 WAI-ARIA 规范，支持键盘操作
• 服务端渲染：完整支持 Next.js 等 SSR 框架
• 暗色模式：内置暗色主题支持

生态图

核心生态

工具与平台

社区生态

• Arco Design Pro Vue：Vue 版本的中后台解决方案
• Arco Work：社区贡献的工作流组件
• Arco CLI 插件：丰富的 CLI 插件扩展

适用场景

• 企业中后台管理系统：Arco Design 的核心定位，60+ 组件覆盖全部后台需求
• 数据密集型应用：强大的 Table 组件支持虚拟滚动、排序、筛选等企业级数据展示
• 多品牌 SaaS 产品：Design Lab 平台支持多主题切换，适合多品牌场景
• 国际化产品：20+ 语言包支持，适合出海业务
• 中大型团队协作：完整的设计规范和物料市场，统一团队开发标准
• 快速原型开发：Arco Pro 模板 + 丰富组件，快速搭建产品原型
• 字节系技术栈项目：与飞书等字节产品的技术栈保持一致

开发与工程化

开发流程

# 使用 Arco CLI 创建项目
npx arco-cli init my-project
 
# 或手动创建
mkdir my-project && cd my-project
npm init vite@latest . -- --template react-ts
npm install @arco-design/web-react
 
# 开发
npm run dev
 
# 构建
npm run build

自定义物料开发

# 使用 Arco CLI 创建物料项目
npx arco-cli init --template material
 
# 物料项目结构
# packages/
#   ├── my-component/        # 自定义组件
#   ├── my-hook/             # 自定义 Hook
#   └── my-block/            # 区块物料
 
# 发布物料到 Material 市场
npx arco-cli publish

Design Lab 主题定制

// 1. 在 Design Lab 平台 (https://arco.design/themes) 定制主题
// 2. 下载主题包
// 3. 引入主题包替代默认样式
 
import '@arco-design/themes/my-custom-theme/index.css'
import { Button } from '@arco-design/web-react'
 
// 组件自动应用自定义主题
function App() {
  return <Button type="primary">Custom Theme</Button>
}

CI/CD 集成

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run build
      - run: npm run test

性能与安全

性能特点

• Tree Shaking：基于 ES Module，未使用组件不会打包
• CSS 按需加载：只加载使用到的组件样式
• 虚拟列表：Table、Select、Tree 等组件支持虚拟滚动
• 懒加载支持：组件支持 React.lazy 动态导入
• 包体积优化：核心包 gzip 后约 200KB

性能优化建议

• 使用按需引入，避免全量引入
• 大表格数据量超过 1000 行时开启虚拟滚动
• 合理使用 React.memo 和 useMemo 减少渲染
• 使用 AutoComplete / Select 的远程搜索时添加防抖
• 动态加载不常用的弹窗类组件（Modal、Drawer）

安全注意事项

• Arco Design 组件不直接渲染 HTML 字符串
• dangerouslySetInnerHTML 使用时需对内容进行消毒处理
• 表单组件支持自定义校验规则
• 定期更新依赖版本，关注安全公告
• 使用 CDN 引入时注意校验文件完整性（SRI）

技术对比

与同类组件库对比

优势分析

• 完整的设计生态：从设计规范到组件库到物料市场，提供一站式解决方案
• Design Lab：在线主题定制平台降低了主题定制的门槛
• 物料市场：社区贡献的物料生态丰富了组件库的能力边界
• 双框架支持：同时提供 React 和 Vue 版本，适合混合技术栈团队
• 包体积友好：相对同级别组件库，gzip 后约 200KB，体积控制较好

劣势分析

• 社区规模不及 Ant Design，第三方资源相对较少
• 与 Semi Design 同属字节系，定位有部分重叠，选型时可能困惑
• 高级定制文档偏向中文，国际化程度有待提升

最佳实践

项目结构推荐

src/
├── components/          # 项目级公共组件
│   ├── Layout/
│   └── PageHeader/
├── pages/               # 页面组件
│   ├── Dashboard/
│   └── UserManagement/
├── hooks/               # 自定义 Hooks
├── utils/               # 工具函数
├── styles/              # 全局样式
│   └── theme.less       # 自定义主题变量
└── locales/             # 国际化文件

主题定制最佳实践

// styles/theme.less
@primary-color: #165DFF;
@border-radius-small: 4px;
@border-radius-medium: 6px;
@font-size-body: 14px;
 
// 引入 Arco 样式（使用 less 变量）
@import '@arco-design/web-react/dist/css/index.less';

表格最佳实践

import { Table, Space, Button, Popconfirm } from '@arco-design/web-react'
import { IconEdit, IconDelete } from '@arco-design/web-react/icon'
 
function UserTable({ data, loading, onDelete }) {
  const columns = [
    { title: '姓名', dataIndex: 'name' },
    { title: '邮箱', dataIndex: 'email' },
    { title: '角色', dataIndex: 'role', render: (col) => <Tag color="blue">{col}</Tag> },
    {
      title: '操作',
      render: (_, record) => (
        <Space>
          <Button icon={<IconEdit />} type="text" size="small" />
          <Popconfirm title="确认删除？" onOk={() => onDelete(record.id)}>
            <Button icon={<IconDelete />} type="text" status="danger" size="small" />
          </Popconfirm>
        </Space>
      ),
    },
  ]
 
  return (
    <Table
      columns={columns}
      data={data}
      loading={loading}
      rowKey="id"
      pagination={{ pageSize: 20 }}
      scroll={{ y: 500 }}
    />
  )
}

常见陷阱

• 避免同时使用 Arco 和 Semi：同属字节系，样式和 API 风格有差异，混用会增加维护成本
• Icon 按需引入：使用 @arco-design/web-react/icon 按需引入图标，避免全量引入
• Table rowKey 必须唯一：确保 rowKey 属性指向数据的唯一标识字段
• 主题变量覆盖顺序：自定义 less 变量需要在引入 Arco less 文件之前定义

技术局限与边界

已知限制

1. 社区规模有限：相比 Ant Design 等头部组件库，社区讨论和第三方资源相对较少
2. 组件更新节奏平稳：非高频迭代型组件库，新组件和 API 更新较为保守
3. 移动端组件库独立：React 移动端组件库与桌面端完全独立，API 不共享
4. 字节系定位重叠：与 Semi Design 在字节内部有不同分工，但外部用户选择时可能困惑

不适用场景

• 需要极大规模社区支持和快速响应的开源项目
• 纯移动端应用（需使用 Arco Design Mobile）
• 对 React Server Components 有强需求的项目

迁移注意事项

• 从 Ant Design 迁移：API 设计思路相似，迁移成本中等，主要差异在命名规范和部分组件 API
• 从 Semi Design 迁移到 Arco：注意主题定制方式差异（Design Lab vs DSM）
• 表单组件的 field 和 name 属性映射需要逐一调整

学习资源

官方资源

• Arco Design 官网
• React 组件文档
• Vue 组件文档
• Arco Design Pro
• Design Lab 主题平台
• 更新日志

教程与文章

• 快速上手指南
• Arco Design 主题定制
• Arco Pro 使用文档

社区资源

• GitHub Issues
• GitHub Discussions
• 字节跳动技术博客

2026 年现状

版本状态

• 最新版本：v2.66.15（2026 年 5 月 8 日发布）
• Beta 版本：v2.67.0-beta.0（2025 年 4 月发布）
• NPM 周下载量：~84,000+
• 总发布数：149+ releases

发展趋势

• ✅ 持续维护：2026 年 5 月仍有新版本发布，维护状态良好
• ✅ 生态完善：Design Lab、IconBox、Material 市场等工具持续完善
• ✅ Vue 生态同步：Vue 3 版本保持同步更新
• 移动端组件库持续迭代
• React 19 兼容性关注中

社区活跃度

• GitHub Stars：~5.6k
• Open Issues / PRs 响应及时
• 在 2025/2026 年 React 组件库推荐榜单中频繁出现
• NPM 下载量稳定，生产环境存量用户较多

选型建议

• 强烈推荐：企业中后台系统、需要完整设计解决方案的团队、飞书技术栈项目
• 适合：多品牌产品（Design Lab）、国际化产品、双框架（React + Vue）团队
• 对比选择：与 Semi Design 同属字节系，Arco 更偏传统企业级，Semi 更偏创新和 AI 方向