Arco Design：字节跳动 React 组件库安装与主题定制指南

官方信息

项目背景：一套完整的企业级设计系统

Arco Design 是字节跳动开源的一套企业级设计系统，而这个仓库是其中基于 React 的 UI 组件库，目前在 GitHub 上有大量使用者和贡献者。它不是一个零散的组件集合，而是一整套设计语言的落地：从设计 Token、视觉规范，到可复用的业务物料、图标平台、中后台前端解决方案，Arco 都提供了对应的平台和工具。对于需要长期维护中后台系统的团队，Arco 希望提供的是「拿来就能用、改起来也方便」的基础能力，而不是只给一堆按钮和表格。

与很多只提供组件的库不同，Arco 把「设计」和「研发」两端的工具都补齐了：设计侧有 Figma 资源和风格配置平台，研发侧有组件库、构建插件和 Arco Pro 脚手架，业务侧有物料平台沉淀可复用模块。这种全家桶式的思路，让团队不需要自己再去拼凑设计规范、组件库和工程脚手架。

它的定位是「全面」：开箱即用的高质量组件可以覆盖绝大部分业务场景，同时围绕组件库构建了风格配置平台、物料平台、图标平台等周边生态，让设计、研发、业务三方能在同一套体系里协作。对中后台系统而言，这种「组件 + 平台 + 物料」的组合意味着：日常开发大部分需求都能直接调用现成组件，遇到反复出现的业务模块就沉淀成物料复用，遇到品牌换肤就走风格配置平台，而不必每次都从零写样式。

Arco 面向的主要是企业级中后台场景：这类系统页面多、表单多、表格多、生命周期长，最需要的是稳定一致的组件和可复用的业务模块，而不是花哨的动效。字节跳动内部大量业务系统都基于 Arco 构建，开源后这套经验也免费对外提供，外部团队可以直接站在大厂的设计实践上。

核心特性

全面：提供 60 多个经过精心打磨的组件，开箱即用，能够覆盖绝大部分业务场景。无论是表单、导航、反馈，还是复杂的数据展示，都有对应的组件支撑。

可定制主题：海量的设计 Token 支持全局和组件级别的主题配置，有两种定制方式：一是通过 less-loader 在构建时注入变量；二是通过风格配置平台在线可视化配置，官方推荐使用后者。这意味着你既可以在代码里精细控制，也可以让设计师在平台上拖拽出一套品牌主题，再把生成的变量交付给研发。主题不是简单换个主色，而是包括色板、圆角、间距、字号等一整套 Token，所有组件会按 Token 自动联动，不会出现某个按钮颜色改了、另一个组件没跟上的情况。

可复用的定制化物料：物料平台提供一站式物料管理方案，把经过验证的业务模块沉淀下来、重复复用，让效率突破式提升。这种「物料沉淀」思路，适合有大量相似业务页面、希望避免重复造轮子的团队。

TypeScript 友好：所有组件都用 TypeScript 编写，天然类型友好，在编辑器里能获得完整的类型提示和自动补全，重构也更安全。

这四项特性是相互配合的：组件「全面」解决有没有的问题，主题可定制解决好不好看的问题，物料复用解决重复造轮子的问题，TypeScript 友好则解决长期维护的问题。一个中后台系统往往要维护好几年，后面接手的人能否快速理解、安全地改代码，很大程度上取决于类型是否完整、组件 API 是否稳定。

环境要求与安装

Arco Design React 组件库以 npm 包形式发布，使用前提是项目中已经有 React 环境。安装命令如下：

# 使用 npm
npm install @arco-design/web-react

# 使用 yarn
yarn add @arco-design/web-react

安装后，在代码里引入组件，同时引入一份组件样式文件 @arco-design/web-react/dist/css/arco.css，即可开始使用。这个 CSS 文件是组件库的完整样式包，引入一次即可；如果项目里使用了按需加载的构建插件，则不需要手动引入全量样式，插件会自动处理。

对 React 版本的要求，只要是现代 React（支持 Hooks 的版本）都可以；组件全部用 TypeScript 编写，安装后自动带上类型定义，在 VS Code 等编辑器里写组件属性时会有完整提示。

使用方法

下面是一个最小可运行示例：引入 Button 组件并渲染一个二级按钮，按钮上显示「Hello World」。整个组件库的用法都和这个例子一致——从 @arco-design/web-react 中按需 import 组件，再在 JSX 中使用。

import React from 'react';
import ReactDOM from 'react-dom';
import { Button } from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';

function App() {
  return (
    <Button type='secondary'>
      Hello World
    </Button>
  );
}

ReactDOM.render(<App />, document.getElementById('app'));

实际项目中，可以通过官方文档站查阅每个组件的完整 API、属性说明和示例；主题定制、暗黑模式、图标使用等都有专门章节。为了让组件按需加载更彻底，Arco 还提供了构建插件，配合 Webpack、Vite 等构建工具自动按需引入样式，避免手动引入全量 CSS 带来的体积浪费。

从这个最小示例也能看出 Arco 的使用约定：组件名即标签，通过 type 等属性控制外观（例如 secondary 表示次要按钮），样式文件统一在入口处引入一份。复杂表单、弹窗、表格等组件也是同样的声明式写法，业务研发主要精力放在数据和交互上，组件外观由设计系统保证。

除了基础组件，Arco 文档站还覆盖了暗黑模式、全局配置、图标使用等专题。暗黑模式通过切换主题 Token 实现，所有组件联动换色，不需要为深色单独写一套样式；图标则由独立的图标平台统一管理，业务里用到的图标集中维护、按需取用。

生态系统

Arco 不只是一个组件库，而是一个完整生态：

其中，Arco Pro 提供了从空项目到可运行中后台的脚手架方案，适合不想从零搭页面骨架的团队；图标平台则统一管理项目里用到的图标，避免各处散落图标文件。风格配置平台可以精确到组件级调整主题视觉，设计师在平台上调好后导出的主题可以直接交给研发使用，不需要研发逐个去翻 Less 变量；物料平台则把业务中反复出现的模块（例如带筛选的表格、统计卡片）沉淀下来，团队内共享，新项目直接引用。整套生态的好处是：设计、研发、业务三方不再各用一套工具，而是围绕同一个 Arco 平台协作，沟通成本和返工率都明显下降。

浏览器兼容性

Arco Design 对浏览器的支持比较广：IE/Edge 支持 Edge 16 及以上，Firefox 支持 31 及以上，Chrome 支持 49 及以上，Safari 支持 31 及以上，Opera 支持 36 及以上，Electron 支持最近两个大版本。这意味着它不仅能跑在现代浏览器里，对一些旧版浏览器和较老的内部系统也能兼容，适合企业内网环境。尤其是 Electron 桌面客户端场景，Arco 明确适配最近两个版本，可以直接用于跨平台桌面应用。

常见问题（FAQ）

问：Arco Design 和 Ant Design 有什么区别？ 答：Arco 是字节跳动开源的 React（也有 Vue 版）组件库，特色是完整的设计系统生态——风格配置平台、物料平台、图标平台和 Arco Pro 脚手架一应俱全，TypeScript 友好，适合中后台系统快速搭建。

问：怎么定制主题？ 答：有两种方式：一是用 less-loader 在构建时覆盖 Less 变量；二是官方推荐的风格配置平台，在线可视化调整后导出主题。组件级别的样式也可以通过设计 Token 精细控制。

问：支持暗黑模式吗？ 答：支持，文档站有专门的暗黑模式章节，配合主题 Token 可以一键切换明暗主题。

问：除了 React，有 Vue 版本吗？ 答：有。Arco 同时提供基于 Arco Design 的 Vue 组件库，API 风格与 React 版保持一致，Vue 技术栈的团队也能使用同一套设计语言。

问：开源协议是什么？ 答：MIT 协议，商用完全免费，企业可以放心在内部产品中使用。

问：如何参与贡献？ 答：贡献前请先阅读仓库里的行为准则和贡献指南，再按规范提 issue 或 Pull Request。

问：组件数量有多少？够用吗？ 答：React 版提供 60 多个高质量组件，覆盖表单、导航、反馈、数据展示等绝大部分业务场景，日常中后台开发基本不需要自己再封装基础组件。

问：样式是全量引入还是按需加载？ 答：官方示例先引入一份 arco.css；在生产项目中，推荐配合构建插件做按需加载，只打包用到组件的样式，减小首屏体积。

问：有没有设计资源（Figma）？ 答：有，官方在 Figma 上提供了 Arco Design System 的组件库文件，设计同学可以直接基于它出稿，与代码组件保持一致。

问：Arco Pro 是做什么的？ 答：它是一个快速构建中后台的前端解决方案（脚手架），把登录、布局、菜单、权限等中后台常见骨架都搭好，团队可以在上面直接写业务页面，而不用从零搭工程。

问：物料平台怎么用？ 答：物料平台提供一站式物料管理，团队把经过验证的业务模块沉淀为可共享物料，新项目直接引用复用，避免每个项目都重写一遍带筛选的表格、统计卡片之类的模块。

问：Arco 的开源协议是什么？商用要收费吗？ 答：MIT 协议，商用免费，几乎没有使用限制，企业可以放心在内部产品中使用。

问：React 和 Vue 两个版本 API 一致吗？ 答：风格保持一致，都是基于同一套 Arco Design 设计语言，但具体 API 以各自文档为准；同一家公司内部如果同时有 React 和 Vue 项目，两套组件库能保持视觉一致。

问：Arco 适合什么规模的团队？ 答：尤其适合需要长期维护多个中后台系统、希望统一设计语言并沉淀业务物料的中大型团队；小项目也可以直接用组件库和 Arco Pro 快速起步，不必一上来就引入整套平台。

问：怎么开始用 Arco？ 答：第一步 npm install @arco-design/web-react，第二步在入口引入 arco.css，第三步照着文档站里的组件示例写第一个页面；需要主题定制时再去风格配置平台，需要搭中后台骨架时直接用 Arco Pro，整个上手过程不需要额外配置。

跳转链接

Arco Design 把组件库、主题配置、物料沉淀、图标管理和脚手架串成了一条完整链路，适合希望以一套设计系统长期维护中后台产品、并在团队内沉淀复用资产的研发团队。以下是常用入口：

• 官方网站：arco.design
• GitHub 仓库：arco-design/arco-design
• 组件文档：arco.design/react/docs/overview
• 暗黑模式：arco.design/react/docs/dark
• 主题配置：arco.design/react/docs/theme
• 风格配置平台：arco.design/themes
• 物料平台：arco.design/material
• 图标平台：arco.design/iconbox
• Arco Pro：arco.design/pro
• Awesome Arco：github.com/arco-design/awesome-arco