shadcn/ui CLI 安装流程完整指南

1.  [shadcn/ui 简介]

2.  [环境准备]

3. [CLI 初始化完整流程]

4. [各选项详细说明]

5.  [常见问题与解决方案]

6.  [安装后操作指南]

一、shadcn/ui 简介

1.1 什么是 shadcn/ui？

shadcn/ui（简称 shadcn）是一个基于 React 的 UI 组件集合，与传统组件库（如 Ant Design、Material UI）有本质区别。

传统库通过 `npm install` 安装为依赖包，组件代码留在 `node_modules` 里，用户只能按文档配置样式。而 shadcn/ui 的理念是**把组件源码直接复制到你的项目中**，代码完全归你所有，想改哪里改哪里。

1.2 CLI 工具的作用

shadcn CLI 是项目初始化和组件管理工具，主要完成两件事：

- **`npx shadcn@latest init`** —— 初始化项目配置。自动完成：安装 Tailwind CSS、配置路径别名、创建 `components.json` 配置文件、设置 CSS 变量主题等。这些手动配起来比较繁琐，CLI 一键搞定。

- **`npx shadcn@latest add <组件名>`** —— 添加组件。比如执行 `npx shadcn@latest add button`，它就会把 Button 组件的完整源码（包括样式、类型定义、依赖的 hooks）下载到你的 `components/ui/` 目录下。

> 💡 **为什么用 CLI 而不是手动复制粘贴？**  

> 每个组件可能有不同的依赖关系（比如 Dialog 依赖 Portal、Select 依赖特定的 hooks），CLI 会自动处理这些依赖链，确保代码完整可用。  

> 你装的不是一个"库"，而是一个"代码生成器 + 脚手架"，帮你把高质量的组件代码搬进项目里。

 二、环境准备

2.1 前置要求

- Node.js 18.17 或更高版本

- npm / yarn / pnpm 包管理器

- Git（用于拉取模板和组件源码）

2.2 网络环境（重要 ⚠️）

由于 shadcn CLI 在初始化时需要通过 Git 连接 GitHub 拉取模板，**国内网络环境可能遇到 SSL 连接错误**。如果遇到此问题，需要配置 Git 代理。

> ⚡ **Git 代理配置命令示例：**

> ```bash

> git config --global http.proxy http://127.0.0.1:7892

> git config --global https.proxy http://127.0.0.1:7892

> ```

> 将端口号替换为你本地实际的代理端口。用完后可取消：

> ```bash

> git config --global --unset http.proxy

> git config --global --unset https.proxy

> ```

三、CLI 初始化完整流程

在终端中执行以下命令开始初始化：

```bash

npx shadcn@latest init

```

3.1 步骤 1：确认安装

终端提示 "Need to install the following packages: shadcn@4.17.0"，输入 `y` 并回车确认安装。

3.2 步骤 2：选择模板 (Select a template)

使用上下箭头键选择框架模板。

最常见的选择：

· Next.js — 如果你在用 Next.js 搭建项目（全栈 React 应用，支持 SSR/SSG），选这个。这是目前最主流的搭配。

· Vite — 如果你只是用 Vite 创建一个纯前端 React 单页应用（SPA），选这个。轻量、启动快。

其他场景：

· TanStack Start — 使用 TanStack Start 框架的项目

· React Router — 基于 React Router v7 的项目

· Astro — Astro 静态站点/内容驱动型项目

· Laravel — Laravel + Inertia.js 的 PHP 全栈项目

如果你不确定，大概率选 Next.js（全栈项目）或 Vite（纯前端项目）就对了。你可以看一下你项目根目录下有没有 next.config.js（对应 Next.js）或 vite.config.ts（对应 Vite）来确认。

这里推荐选择 Next.js（全栈 React 应用）或 Vite（纯前端 SPA）。本指南以 Next.js 为例。

3.3 步骤 3：Monorepo 设置

询问 "Would you like to set up a monorepo?"，根据项目需求选择 yes 或 no。Monorepo 适合管理多个相关包/应用的项目结构。

3.4 步骤 4：选择组件库 (Select a component library)

选项包括 Base UI（推荐）、React Aria、Radix UI。**推荐选择 Base UI**，这是 shadcn 官方当前主推的无头组件库，由原 Radix UI 核心团队开发。

如果你是新项目，直接选 Base UI，跟着官方推荐走不会有问题。

3.5 步骤 5：选择预设主题 (Which preset)

shadcn提供多种配色预设：Nova（默认）、Vega、Maia、Lyra、Mira、Luma、Sera、Rhea、Custom。这些预设仅影响默认配色方案（主色、背景色、圆角等 CSS 变量的组合）。它们之间没有功能差异，纯粹是视觉风格的不同。

建议：

• 如果你没有特别的设计需求 → 直接选 Nova（默认预设，中性现代风格），后续可以随时改。

• 如果你已经有明确的品牌色或想要完全自定义 → 选 Custom。

这些预设本质上只是帮你预填了 globals.css 里的 CSS 变量，初始化之后想换配色随时可以调整，所以不用纠结太久。

3.6 步骤 6：输入项目名称

输入你的项目名称，如 `admin-dashboard`。默认的 next-monorepo 只是 CLI 给的占位符。

直接输入你自己的项目名然后回车就行，比如：

• 如果你在做个人博客 → my-blog

• 如果是公司内部项目 → admin-dashboard

• 如果没有特别的想法，随便起一个也行，后续可以改命名建议使用小写字母、数字和短横线（`-`），避免空格和大写字母。

3.7 步骤 7：等待创建完成

此过程可能需要几分钟，请耐心等待。CLI会自动完成以下事情：

1. 创建 monorepo 项目结构

2. 初始化 Next.js 应用

3. 配置 Base UI + Nova 主题预设

4. 安装所有依赖

5. 创建示例组件

6. 配置主题样式

7. 配置字体

等它跑完后，通常会在终端输出下一步的操作指引，一般是 cd admin-dashboard 然后 npm run dev 启动开发服务器。之后你就可以用 npx shadcn@latest add <组件名> 来按需添加组件了。

 四、各选项详细说明

 4.1 模板选项对比

4.2 组件库选项对比

4.3 主题预设说明

所有预设（Nova/Vega/Maia/Lyra/Mira/Luma/Sera/Rhea）本质上是不同的 CSS 变量组合，影响项目的配色方案（主色、背景色、圆角等）。它们之间**没有功能差异**，纯粹是视觉风格不同。

如果选择 Custom，则可以完全自定义配色。无论选哪个，后续都可以通过修改 `globals.css` 中的 CSS 变量来调整。

五、常见问题与解决方案

 5.1 SSL 连接错误（最常见）

原因：Git 连接 GitHub 时网络不通或被拦截。

解决方案（按优先级排序）：

1. 设置 Git 代理（见第二章 2.2 节）—— 最推荐

2. 尝试旧版本： `npx shadcn@4.16.0 init`

3. 临时关闭 SSL 验证： `git config --global http.sslVerify false`（不推荐长期使用）

4. 手动创建项目后单独 init

5.2 手动创建项目（备选方案）

如果 CLI 一键初始化持续失败，可以分步手动操作：

```bash

• 第一步：手动创建 Next.js 项目

npx create-next-app@latest admin-dashboard

• 第二步：进入项目目录

cd admin-dashboard

• 第三步：单独运行 shadcn init

npx shadcn@latest init

```

 六、安装后操作指南

6.1 启动开发服务器

进入项目目录并启动：

```bash

cd admin-dashboard

npm run dev

```

然后在浏览器打开 `http://localhost:3000`（实际端口以终端输出为准）。

6.2 添加组件

使用 `add` 命令按需添加组件：

```bash

• 添加单个组件

npx shadcn@latest add button

• 同时添加多个组件

npx shadcn@latest add card input table dialog

```

💡 **管理后台常用组件推荐：**

> - card（卡片容器）

> - table（数据表格）

> - input（输入框）

> - select（下拉选择）

> - dialog（对话框/模态框）

> - dropdown-menu（下拉菜单）

> - sidebar（侧边栏导航）

> - button（按钮，已预装）

> - badge（标签/徽章）

> - separator（分隔线）

6.3 初始化完成后生成的文件

 6.4 更多资源

- **shadcn/ui 官网：** 

https://ui.shadcn.com

 （浏览所有可用组件及文档）

- **GitHub 仓库：** 

https://github.com/shadcn-ui/ui

- 组件添加后可在官网查看每个组件的使用示例和 API 文档。