shadcn-vue

shadcn-vue 生产技术栈

经过生产环境验证：具有无障碍、可自定义组件的 Vue/Nuxt 应用 最后更新：2025-12-09 状态：已可用于生产环境 ✅ 最新版本：shadcn-vue@latest（Reka UI v2） 依赖项：Tailwind CSS、Reka UI、Vue 3+ 或 Nuxt 3+

---

快速开始（3 分钟）

Vue 项目（Vite）

1. 初始化 shadcn-vue

# Using Bun (recommended)
bunx shadcn-vue@latest init

# Using npm
npx shadcn-vue@latest init

初始化期间：

• 样式：New York 或 Default（之后无法更改！）
• 基础颜色：Slate（推荐）
• CSS 变量：Yes（深色模式必需）

2. 配置 TypeScript 路径别名

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. 配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite' // Tailwind v4
import path from 'path'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

4. 添加第一个组件

bunx shadcn-vue@latest add button
# or: npx shadcn-vue@latest add button

查看完整设置：templates/quick-setup.ts

---

Nuxt 项目

# Create project with Tailwind
bun create nuxt-app my-app
cd my-app
bun add -D @nuxtjs/tailwindcss

# Configure Nuxt
# nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss']
})

# Initialize shadcn-vue
bunx shadcn-vue@latest init
# or: npx shadcn-vue@latest init
# or: pnpm dlx shadcn-vue@latest init

---

组件库（50+ 个组件）

导航与布局

• Accordion、Alert Dialog、Avatar、Badge、Breadcrumb、Card、Carousel、Collapsible、Dialog、Drawer、Dropdown Menu、Menu Bar、Navigation Menu、Pagination、Popover、Resizable、Scroll Area、Sheet、Sidebar、Tabs、Toast、Tooltip

表单组件

• Auto Form、Button、Calendar、Checkbox、Combobox、Command、Context Menu、Date Picker、Form、Input、Input OTP、Label、Number Field、PIN Input、Radio Group、Range Calendar、Select、Slider、Sonner、Switch、Textarea、Toggle、Toggle Group

数据展示

• Aspect Ratio、Data Table、Skeleton、Stepper、Splitter、Table、Tag Input

高级组件

• 图表（Unovis）、Color Picker、Editable、File Upload、Sortable

完整组件参考：https://shadcn-vue.com/docs/components

---

Auto Form - 基于架构的表单

安装

bunx shadcn-vue@latest add auto-form
# or: npx shadcn-vue@latest add auto-form

bun add zod
# or: npm install zod

基本用法

<script setup lang="ts">
import { AutoForm } from '@/components/ui/auto-form'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.email({ error: 'Invalid email' }),
  age: z.number().min(18, 'Must be 18 or older'),
  bio: z.string().optional(),
  subscribe: z.boolean().default(false)
})

function onSubmit(values: z.infer<typeof schema>) {
  console.log('Form submitted:', values)
}
</script>

<template>
  <AutoForm :schema="schema" @submit="onSubmit">
    <template #submit>
      <Button type="submit">Submit</Button>
    </template>
  </AutoForm>
</template>

支持的字段类型：string、number、boolean、date、enum、array、object

---

使用 TanStack Table 的数据表

安装

bunx shadcn-vue@latest add data-table
# or: npx shadcn-vue@latest add data-table

bun add @tanstack/vue-table
# or: npm install @tanstack/vue-table

基本设置

<script setup lang="ts">
import { DataTable } from '@/components/ui/data-table'
import { h } from 'vue'

const columns = [
  {
    accessorKey: 'id',
    header: 'ID',
  },
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'email',
    header: 'Email',
  }
]

const data = [
  { id: 1, name: 'John Doe', email: '[email protected]' },
  { id: 2, name: 'Jane Smith', email: '[email protected]' }
]
</script>

<template>
  <DataTable :columns="columns" :data="data" />
</template>

功能：排序、筛选、分页、行选择、列可见性、可展开行

---

深色模式实现

安装

bun add @vueuse/core
# or: npm install @vueuse/core

设置主题提供程序

<script setup lang="ts">
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()
</script>

<template>
  <div :class="mode">
    <slot />
  </div>
</template>

在组件中使用

<script setup>
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()

function toggleTheme() {
  mode.value = mode.value === 'dark' ? 'light' : 'dark'
}
</script>

<template>
  <Button @click="toggleTheme">
    {{ mode === 'dark' ? '🌙' : '☀️' }}
  </Button>
</template>

---

关键规则

始终执行

✅ 添加组件前先运行 init

• 创建必需的配置和工具
• 设置路径别名

✅ 使用 CSS 变量进行主题设置（cssVariables: true）

• 支持深色模式
• 灵活自定义主题

✅ 配置 TypeScript 路径别名

• 导入组件必需
• 必须与 components.json 中的别名一致

✅ 将 components.json 纳入版本控制

• 团队成员需要使用相同配置
• 记录项目设置

✅ 使用 Bun 加快安装速度（推荐）

• 比 npm 快 10-20 倍

绝不执行

❌ 初始化后不要更改 style

• 需要完整重新安装
• 请改为在新目录中重新初始化

❌ 不要混用 Radix Vue 和 Reka UI v2

• 组件 API 不兼容
• 二选一使用

❌ 不要跳过 TypeScript 配置

• 组件导入会失败
• IDE 自动补全无法使用

❌ 不要在未使用 Tailwind CSS 的情况下使用

• 组件使用 Tailwind 设置样式
• 无法正确渲染

---

7 个最关键的问题

问题 #1：缺少 TypeScript 路径别名

错误：Cannot find module '@/components/ui/button'

解决方案：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

---

问题 #2：未配置 Tailwind CSS

错误：组件渲染时没有样式

解决方案：

/* src/assets/index.css */
@import "tailwindcss";

// vite.config.ts (Tailwind v4)
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()]
})

---

问题 #3：未定义 CSS 变量

错误：主题颜色未生效，组件呈灰色或透明

解决方案：确保定义了所有 CSS 变量（运行 init 命令）

---

问题 #4：选择了错误的样式

错误：组件外观与预期不符

解决方案：在 init 期间谨慎选择（New York 或 Default）——之后无法更改，除非重新安装

---

问题 #5：混用 Radix Vue 和 Reka UI

错误：类型冲突、组件重复

解决方案：

• 使用 bunx shadcn-vue@latest 安装 Reka UI v2
• 使用 bunx shadcn-vue@radix 安装旧版 Radix Vue
• 不要混用两者

---

问题 #6：Monorepo 路径问题

错误：组件安装到了错误的目录

解决方案：使用 -c 标志指定工作区：

bunx shadcn-vue@latest init -c ./apps/web
bunx shadcn-vue@latest add button -c ./apps/web

---

问题 #7：手动编辑后组件导入失败

错误：编辑 components.json 后导入路径失效

解决方案：保持 components.json 和 tsconfig.json 别名同步。任何配置更改后都要测试导入。

---

查看全部 7 个问题：references/error-catalog.md

---

CLI 命令参考

init 命令

# Initialize in current directory
bunx shadcn-vue@latest init
# or: npx shadcn-vue@latest init

# Initialize in specific directory (monorepo)
bunx shadcn-vue@latest init -c ./apps/web
# or: npx shadcn-vue@latest init -c ./apps/web

add 命令

# Add single component
bunx shadcn-vue@latest add button
# or: npx shadcn-vue@latest add button

# Add multiple components
bunx shadcn-vue@latest add button card dialog

# Add all components
bunx shadcn-vue@latest add --all
# or: npx shadcn-vue@latest add --all

diff 命令

# Check for component updates
bunx shadcn-vue@latest diff button
# or: npx shadcn-vue@latest diff button

---

Reka UI v2 迁移

shadcn-vue 现在基于 Reka UI v2（原 Radix Vue）。所有新组件都使用 Reka UI 基元。

**迁移：**现有项目应升级到 Reka UI v2。请参阅官方迁移指南：shadcn-vue.com/docs/changelog#reka-ui

---

配置

shadcn-vue 使用 components.json 进行以下配置：

• 组件路径（@/components/ui）
• Utils 位置（@/lib/utils）
• Tailwind 配置路径
• TypeScript 路径

**完整示例：**请参阅 templates/components.json，或通过 bunx shadcn-vue@latest init 生成

---

Utils 库

@/lib/utils.ts 文件提供了用于合并 Tailwind 类的 cn() 助手函数：

• 合并多个 className 字符串
• 使用 clsx + tailwind-merge 解决冲突

由 shadcn-vue init 自动生成，无需手动设置。

---

捆绑资源

模板（templates/）：

• quick-setup.ts - Vue/Nuxt 完整设置指南，附带示例（190 行）

参考资料（references/）：

• error-catalog.md - 已记录的全部 7 个问题及解决方案（267 行）

---

何时加载参考资料

根据任务加载以下参考资料：

1. 在以下情况下加载 references/error-catalog.md：

   • 用户遇到“找不到组件”或导入错误
   • 设置命令失败或出现配置问题
   • Tailwind CSS 变量或 TypeScript 路径失效
   • 触发短语：“无法正常工作”、“错误”、“失败”、“失效”

2. 在以下情况下加载 references/component-examples.md：

   • 用户询问“如何实现[组件]？”
   • 需要特定组件的可复制粘贴示例
   • 构建表单、表格、导航或数据显示
   • 触发短语：“示例”、“如何使用”、“实现”、“代码示例”

3. 在以下情况下加载 references/dark-mode-setup.md：

   • 实现深色模式／主题切换
   • 用户提到 Vue 3 + Vite、Nuxt 或 Astro 设置
   • 需要主题管理的组合式函数模式
   • 触发短语：“深色模式”、“主题”、“浅色／深色”、“配色方案”

---

与其他技能集成

此技能可与以下技能良好配合：

• nuxt-v4 → Nuxt 框架
• tailwind-v4-shadcn → 搭配 React shadcn/ui 的 Tailwind v4
• react-hook-form-zod → 表单验证模式（与 Auto Form 类似）
• tanstack-query → 表格数据获取
• zustand-state-management → 状态管理

---

资源

参考资料（references/）：

• component-examples.md - 全部 50 多个组件示例及代码
• dark-mode-setup.md - 深色模式完整实现指南
• error-catalog.md - 常见错误及解决方案

模板（templates/）：

• 组件模板可在 references/component-examples.md 中找到

---

安全安装

设置期间安装软件包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新软件包版本
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

附加资源

官方文档：

• shadcn-vue 文档：https://shadcn-vue.com
• Reka UI 文档：https://reka-ui.com
• GitHub：https://github.com/radix-vue/shadcn-vue

示例：

• 组件示例：https://shadcn-vue.com/examples
• 入门模板：https://github.com/radix-vue/shadcn-vue/tree/main/templates

---

已在生产环境中测试：Vue/Nuxt 应用、管理后台、内容管理系统 上次更新：2025-12-09 Token 节省：约 65%（减少设置和组件文档内容）