企业官网建设流程全解析

shadcn-vue 在 Laravel + Inertia + Vue 项目中的安装与组件接入指南

【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vue

本篇指南面向 Laravel 开发者，讲解如何在基于 Inertia + Vue 的 Laravel 项目中接入 shadcn-vue 组件库：从使用laravel new创建项目、通过 CLI 一键添加组件，到在 Vue 单文件组件中正确导入与渲染 UI 组件。读完本文，你将掌握 shadcn-vue 在 Laravel 生态下的完整接入流程，并理解 CLI 底层的工作机制与@路径别名的配置原理。

前置条件：确认 Tailwind 版本

在开始之前，请先确认项目使用的 Tailwind CSS 版本，因为它直接决定了应该安装哪个版本的 shadcn-vue CLI：

• Tailwind v4：使用最新版 CLI，即npx shadcn-vue@latest；
• Tailwind v3：使用shadcn-vue@1.0.3这个固定版本，例如npx shadcn-vue@1.0.3 add switch。

这一版本约束在 shadcn-vue 官方安装文档（deprecated/www/src/content/docs/installation/laravel.md）中被明确标注。原因在于 Tailwind v4 引入了全新的 Vite 插件机制（@tailwindcss/vite）与 CSS-first 配置方式，与 v3 的tailwind.config.js体系不兼容，因此两代 CLI 需要分别适配。

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

使用 Laravel 官方安装器创建一个预置了 Inertia 与 Vue 的 Laravel 项目：

laravel new my-app --vue

--vue标志会自动完成以下脚手架工作：

• 安装laravel-vite-plugin、@vitejs/plugin-vue与 Vue 3；
• 注册 Inertia 服务端中间件与客户端适配层；
• 生成resources/js目录作为前端源码根目录。

完成创建后，进入项目目录：

cd my-app

创建出的项目结构即 shadcn-vue CLI 检测 Laravel 框架的依据：前端资源集中在resources/js，入口样式为resources/css/app.css。仓库自带的 Laravel 模板（templates/laravel/vite.config.ts）展示了这套典型配置：

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', }, }, })

注意其中resolve.alias将@指向/resources/js，这与本文后续组件导入路径@/Components/ui/switch一一对应，是组件能够正确解析的前提。

第二步：添加 shadcn-vue 组件

项目就绪后，使用 CLI 添加组件。以Switch（开关）组件为例：

npx shadcn-vue@latest add switch

执行过程中 CLI 会做几件事：

1. 检测项目框架：读取项目结构，识别出这是 Laravel 项目，从而将组件安装到resources/js/components/ui/switch而非默认的src/components/ui；
2. 拉取注册表：从 registry 获取switch组件的元数据与源码文件（包含.vue组件本体及其依赖的SwitchControl、SwitchThumb等子组件与index.ts导出文件）；
3. 写入文件：将组件文件落盘，同时确保 Tailwind 配置、CSS 变量等基础设置就绪；
4. 输出摘要：显示已添加/更新的文件清单。

从 CLI 源码（packages/cli/src/commands/add.ts）可以看到add命令还支持多种实用选项，便于批量操作与自动化：

例如，静默批量安装多个组件：

npx shadcn-vue@latest add button card input -y --silent

关于 init 与 components.json

本文聚焦于组件添加环节；如果你的项目尚未初始化过 shadcn-vue，CLI 在首次运行时也会引导生成components.json配置文件（定义style、aliases、tailwind等项）。对于 Laravel 项目，@别名需同时满足两处要求：

• Vite 侧：resolve.alias中'@'指向/resources/js（见上文模板）；
• TypeScript 侧：tsconfig.json的compilerOptions.paths配置"@/*": ["./resources/js/*"]。

仓库的 Laravel 模板（templates/laravel/tsconfig.json）已包含完整示例，同时它启用了strict、noUnusedLocals等严格检查选项，并默认基于moduleResolution: "bundler"工作。

第三步：导入并使用组件

add switch命令执行完毕后，Switch组件会被安装到resources/js/components/ui/switch。在任意 Vue 组件中按如下方式导入使用：

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

要点说明：

• 导入路径使用@别名（即resources/js目录），因此@/Components/ui/switch实际解析到resources/js/components/ui/switch；
• Switch组件默认使用 TypeScript 编写，项目需具备.vue的类型支持（Vite 的vue-tsc与 tsconfig 中的"include": ["resources/**/*.vue"]已覆盖）；
• 组件开箱即用，样式由 shadcn-vue 基于 Tailwind v4 的 CSS 变量体系提供，无需额外引入 CSS 文件。

常见问题与排错

Q1：运行add命令时提示找不到项目配置？请确认当前处于 Laravel 项目根目录，且前端资源确实位于resources/js下。CLI 通过检测package.json、vite.config.ts等文件推断框架类型（Laravel 场景下还会识别laravel-vite-plugin）。

Q2：组件导入路径报错（模块无法解析）？检查两处配置是否一致：vite.config.ts的resolve.alias与tsconfig.json的paths。二者必须同时将@映射到resources/js，否则 IDE 类型提示与 Vite 打包会出现不一致。

Q3：使用了 Tailwind v3 但装了最新版 CLI？请改用npx shadcn-vue@1.0.3，详见本文「前置条件」一节。

Q4：如何查看添加组件时具体改动了哪些文件？使用--dry-run先预览，或直接查看resources/js/components/ui/switch目录下的文件清单（包含.vue子组件与index.ts）。

延伸阅读

• 其他前端框架接入指南见 deprecated/www/src/content/docs/installation/ 目录（如 vite.md、nuxt.md），手动配置方式可参考 manual.md；
• CLI 全部命令定义位于 packages/cli/src/commands/；
• Laravel 场景的最小可运行模板见 templates/laravel/，其中package.json列出了laravel-vite-plugin、@tailwindcss/vite、vue-tsc等关键依赖及dev/build脚本。

【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vue