在企业级前端开发领域，UI 组件库的选择直接影响产品的开发效率、维护成本和用户体验。当项目需要快速搭建专业、统一的企业级应用时，一套成熟的设计体系往往能事半功倍。Arco Design 正是这样一款由字节跳动出品的、经过大规模业务验证的企业级设计系统。
Arco Design 的诞生源于字节跳动内部“开源协同”的实践。过去，字节跳动内部众多团队各自维护独立的设计体系和组件库，彼此割裂，重复造轮子的现象严重。为了解决这一问题，字节跳动内部建立了开源协同机制，将同类项目的不同技术团队聚合在一起，共建共享。Arco Design 在这样的背景下应运而生，来自字节跳动内部近 300 名设计师与开发者共同参与，经由 4000+ 项目的使用、验证和锤炼，覆盖了西瓜视频、火山引擎、今日头条、番茄小说等字节跳动核心产品线。
本文将系统全面地梳理 Arco Design React 的核心知识点，从设计理念到安装配置，从组件体系到主题定制，从国际化到性能优化，帮助读者建立完整的知识体系，能够熟练运用 Arco Design 构建高质量的企业级 React 应用。
一、Arco Design 概述
1.1 什么是 Arco Design
Arco Design 是字节跳动出品的一套完整的企业级设计系统，而不仅仅是一个 UI 组件库。它包含了设计语言、React 组件库、Vue 组件库、主题工具、设计资源、图标平台等完整生态。
与市面上其他组件库相比，Arco Design 的定位更加系统和全面：
Arco Design 的核心理念可以概括为”全面、可定制、类型友好“。它提供了超过 60 个精心打造的组件，开箱即用，覆盖中后台开发绝大部分场景；同时拥有丰富的 Design Token，支持两种主题定制方式，满足品牌化需求；所有组件使用 TypeScript 编写，提供完整的类型定义，IDE 支持完善。
根据字节跳动的官方介绍，“Arco Design 是一套企业级产品设计系统，由字节跳动 GIP UED 和架构前端团队联合打造，致力于为设计师和开发者提供高效、一致、愉悦的产品体验”。
1.2 技术栈与设计理念
Arco Design 采用现代化的前端技术栈构建，其核心组件库基于 React 开发，具有以下特点：
Arco Design 的设计系统分为几个层次：设计资源层（Figma、Sketch 等设计工具资源）、组件库层（React/Vue 组件实现）、生态工具层（Design Lab、Icon Box、Material Market）和应用层（Arco Pro 后台模板）。
1.3 Arco Design vs Ant Design vs Semi Design
这是开发者最常问的问题。三者代表了三种不同的设计哲学和背景：
选择建议：
选择 Arco Design：追求现代设计语言、需要完善的设计生态工具、项目需要 Vue 和 React 双版本支持
选择 Ant Design：需要最丰富的社区资源和文档、需要微信小程序和 React Native 支持
选择 Semi Design：追求极致的设计体验和主题定制能力，项目仅需 React 版本
需要注意的是，Semi Design 官方已明确不支持移动端，因为字节跳动内部移动端使用一套独立的移动端组件库（未开源）。而 Arco Design 提供 React 和 Vue 双版本支持，在技术栈选择上更加灵活。
二、安装与配置
2.1 环境准备
在使用 Arco Design 之前，请确保开发环境满足以下要求：
React 16.8+（支持 Hooks）
Node.js 14.x 或更高版本
TypeScript 4.0+（可选，推荐）
2.2 npm 安装（推荐）
# 使用 npm 安装
npm install @arco-design/web-react
# 使用 yarn 安装
yarn add @arco-design/web-react
# 使用 pnpm 安装（推荐）
pnpm add @arco-design/web-react
2.3 基础使用
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='primary'>
主要按钮
</Button>
);
}
ReactDOM.render(<App />, document.getElementById('app'));
⚠️ 重要提示：必须引入 arco.css 样式文件，否则组件样式不会生效。
2.4 按需引入（性能优化推荐）
Arco Design 支持按需引入，可以显著减小打包体积。推荐使用 babel-plugin-import 插件实现自动按需引入。
步骤 1：安装 babel-plugin-import
npm install babel-plugin-import -D
步骤 2：配置 babel.config.js
module.exports = {
plugins: [
['import', {
libraryName: '@arco-design/web-react',
libraryDirectory: 'es',
camel2DashComponentName: false,
style: true, // 自动加载样式
}],
],
};
配置完成后，可以像下面这样使用组件，插件会自动处理样式引入：
import { Button } from '@arco-design/web-react';
// 样式会自动按需引入，无需手动导入 arco.css
2.5 在 Umi 项目中集成
如果你使用 Umi 框架，可以通过官方插件更简单地集成 Arco Design。
npm install @arco-design/web-react @umijs/plugins -S
配置 .umirc.ts：
export default {
plugins: ['@umijs/plugins/dist/arco'],
arco: {
import: true,
theme: 'light',
},
};
2.6 TypeScript 支持
Arco Design 使用 TypeScript 编写，提供完整的类型定义。在 TypeScript 项目中使用时，可以获得完整的类型提示和校验：
import { Button, ButtonProps } from '@arco-design/web-react';
const CustomButton: React.FC<ButtonProps> = (props) => {
// props 会有完整的类型提示
return <Button {...props} />;
};
