在 Laravel + Inertia + Vue 项目中安装 shadcn-vue 组件库

原创2026-09-23 15:05:542,146 阅读
文章标签:前端UI组件设计系统CLI文档MCP 服务AI 技能

在 Laravel + Inertia + Vue 项目中安装 shadcn-vue 组件库

shadcn-vue 是 shadcn-ui 的 Vue 移植版,通过 CLI 将可复制、可定制的组件源码直接写入项目,而非以运行时依赖的方式引入。本文以仓库文档 apps/v4/content/docs/installation/04.laravel.md 为主线,完整讲解如何在基于 Laravel 与 Inertia 的 Vue 前端项目中安装 shadcn-vue,并深入 CLI 源码与官方模板,说明路径别名、Tailwind 内容扫描等底层机制。读完本文,你将掌握从 laravel new 到第一个 Switch 组件落地页面的完整流程。

前置环境

在开始之前,请确认本机已具备:

  • Laravel 安装器(laravel installer):本文与官方文档均使用 laravel new 脚手架创建项目,该命令由 Laravel Installer 提供;
  • PHP 与 Composer:运行 Laravel 应用的基础运行时;
  • Node.js 与 npm(或 pnpm/yarn):shadcn-vue 的 CLI 依赖 npx,前端资源构建依赖 Vite;
  • Tailwind CSS 环境:shadcn-vue 组件全部基于 Tailwind CSS 样式化,--vue 脚手架生成的 Laravel 项目已默认集成。

第一步:创建 Laravel + Inertia + Vue 项目

在终端执行:

laravel new my-app --vue

--vue 标志会使用官方 Laravel Vue 技术栈脚手架,自动安装并配置 Inertia 与 Vue 3,生成以下典型目录结构(与本文后续步骤相关的部分):

my-app/
├── resources/
│   ├── css/
│   │   └── app.css          # 全局样式(Tailwind 入口)
│   ├── js/
│   │   ├── app.ts           # Vite 入口文件
│   │   ├── pages/           # Inertia 页面组件(如 index.vue)
│   │   └── components/      # Vue 组件
│   └── views/               # Blade 模板(Inertia 挂载点)
├── routes/
│   └── web.php              # 服务端路由
├── vite.config.ts           # Vite + laravel-vite-plugin 配置
├── tsconfig.json            # TypeScript 与路径别名配置
└── package.json

注意:shadcn-vue 的组件将被写入 resources/js 目录,而不是常见的 src/,这是 Laravel + Inertia 项目与纯 Vite/Vue 项目最大的路径差异。

第二步:添加 shadcn-vue 组件

创建好项目后,在 my-app 目录下直接运行 CLI 添加组件:

npx shadcn-vue@latest add switch

该命令会完成以下工作:

  1. 从 shadcn-vue 注册表(registry)拉取 Switch 组件的源码;
  2. 将其写入 resources/js/components/ui/switch 目录(默认 ui 别名路径);
  3. 自动补齐组件依赖的 utils(cn 工具函数)与基础样式文件。

文档明确说明,执行后组件文件会落在:

resources/js/components/ui/switch

这里默认的 @/components、@/lib 等别名,正是针对 Laravel 项目 resources/js 目录推导出来的,细节见下文「CLI 如何识别 Laravel 项目」。

第三步:在页面中引入并使用组件

在 Inertia 页面组件(如 resources/js/pages/index.vue)中导入 Switch:

<script setup lang="ts">
import { Switch } from '@/Components/ui/switch'
</script>

<template>
  <div>
    <Switch />
  </div>
</template>

几个值得注意的要点:

  • 导入路径使用了 @ 别名,指向 resources/js 目录(配置见下文);
  • 官方文档示例中路径写为 @/Components/ui/switch(首字母大写),而 CLI 实际生成的目录名通常是全小写 @/components/ui/switch,两者指向同一文件,Linux/macOS 下大小写敏感的项目请以实际生成的目录名为准;
  • <Switch /> 组件的默认导出即完整的开关组件,可直接嵌套在任意 Vue 模板中。

若添加的是 button、dialog 等其他组件,使用方式完全一致:先 npx shadcn-vue@latest add <组件名>,再从 @/components/ui/<组件名> 导入。

深入:CLI 如何识别 Laravel 项目

add 命令之所以能把组件写入 resources/js 并正确解析别名,是因为 CLI 内置了对各前端框架的探测能力。

在 packages/cli/src/utils/frameworks.ts 中,laravel 被定义为一个受支持的框架类型,其安装文档指向本站 /docs/installation/laravel(即本文对应的 04.laravel.md),Tailwind 安装指引指向 Laravel 官方指南。CLI 通过检测项目结构(如 vite.config.ts 中是否使用 laravel-vite-plugin、resources/js 目录是否存在)来判定框架,从而选择正确的默认路径。

在 packages/cli/src/commands/init.ts 中,init 命令(别名 create)还提供 --template 选项,明确支持 laravel 模板:

npx shadcn-vue@latest init --template laravel

其选项校验代码明确列出了合法模板集合 'nuxt', 'vite', 'astro', 'laravel',并在交互式提问中展示 Laravel 选项。也就是说,CLI 既支持在已有 Laravel 项目中直接 add,也支持以 Laravel 为模板从零初始化。

深入:Laravel 项目的 Tailwind 内容扫描与别名配置

Tailwind content 路径

shadcn-vue 组件样式依赖 Tailwind 的 content 扫描。在 packages/cli/src/utils/templates.ts 中,当框架为 laravel 时,CLI 生成的 Tailwind 配置会包含 Laravel 特有的扫描范围:

content: [
  "./vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php",
  "./storage/framework/views/*.php",
  "./resources/views/**/*.blade.php",
  "./resources/js/**/*.{js,jsx,ts,tsx,vue}",
],

这确保 Blade 模板、分页视图与 resources/js 下的 Vue 组件都能被 Tailwind 正确收集类名——这是 Laravel 项目与纯前端项目在样式配置上的核心差异。

路径别名:vite.config.ts 与 tsconfig.json

仓库中的官方模板 templates/laravel/vite.config.ts 展示了 Laravel + Vite 的关键配置:

import tailwindcss from '@tailwindcss/vite'
import vue from '@vitejs/plugin-vue'
import laravel from 'laravel-vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/css/app.css', 'resources/js/app.ts'],
      refresh: true,
    }),
    vue(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      '@': '/resources/js',
    },
  },
})

要点:

  • laravel() 插件声明了构建入口为 resources/css/app.css 与 resources/js/app.ts,refresh: true 启用 Blade 模板热更新;
  • resolve.alias 将 @ 映射到 /resources/js,使 import { Switch } from '@/Components/ui/switch' 得以解析;
  • tailwindcss() 插件对应 Tailwind CSS v4(见 templates/laravel/package.json 中 tailwindcss: ^4.0.0 与 @tailwindcss/vite: ^4.0.0)。

同时 templates/laravel/tsconfig.json 中通过 paths 同步声明了类型层面的别名,保证 IDE 与 vue-tsc 类型检查可用:

"paths": {
  "@/*": ["./resources/js/*"]
}

模板 templates/laravel/package.json 还展示了该技术栈的依赖集合:vue、laravel-vite-plugin、@vitejs/plugin-vue、@tailwindcss/vite、tailwindcss、typescript、vue-tsc 与 vite,其中构建脚本为 vue-tsc -b && vite build。如果你采用手动方式安装,可以直接参考这份模板作为基准配置。

手动安装方式(无 CLI 场景)

如果希望不依赖 CLI 手动接入,可参考仓库文档 apps/v4/content/docs/installation/05.manual.md。其核心步骤为:安装 Tailwind CSS 与 class-variance-authority clsx tailwind-merge @lucide/vue tw-animate-css 等依赖;在 tsconfig.json 配置 @/* 路径别名;在全局 CSS 中导入 tailwindcss 与 tw-animate-css 并声明 :root/.dark 主题变量;最后在项目根目录创建 components.json,其中 aliases.components、aliases.utils 等字段指向 @/components、@/lib/utils,并保证 tailwind.css 指向真实的全局样式文件路径。手动方式的样式与主题变量细节,可进一步阅读 apps/v4/content/docs/04.theming.md。

其他框架的安装对照

如果你在多个前端栈之间切换,仓库还提供了平行的安装文档:

与 Vite 版最大的区别在于:Laravel 项目的前端资源位于 resources/js,别名从 ./src/* 变为 ./resources/js/*,其余「运行 CLI → 添加组件 → 导入使用」的体验完全一致。

验证与运行

完成上述步骤后,启动开发服务器即可在页面中看到 Switch 组件:

# 前端资源构建
npm run dev

# 或另开终端启动 Laravel 服务
php artisan serve

打开浏览器访问 http://localhost:8000(或 laravel new 配置的本地域名),在 resources/js/pages/index.vue 渲染的页面上即可交互使用开关组件。之后可继续通过 npx shadcn-vue@latest add <组件名> 按需添加更多组件,所有组件都位于 resources/js/components/ui/ 下,源码完全归你所有,可直接修改样式与逻辑。

登录后查看全文
shadcn-vue