shadcn-vue 在 Vite 项目中的安装与配置指南（Tailwind CSS v4 版）

shadcn-vue 在 Vite 项目中的安装与配置指南Tailwind CSS v4 版【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vue本篇指南以 shadcn-vue 官方 Vite 安装文档deprecated/www/src/content/docs/installation/vite.md为主线完整讲解如何在 Vite Vue 3 TypeScript 项目中从零接入 shadcn-vue包括创建项目、集成 Tailwind CSS v4、配置 TypeScript 路径别名与 Vite 解析、运行 CLI 初始化、以及添加并引用首个组件。文末结合仓库源码CLI 实现与官方模板补充底层原理帮助你理解init与add命令背后到底做了什么读完即可独立完成一次干净、可复现的安装。版本提示本指南面向Tailwind CSS v4。如果你仍在使用 Tailwind v3请改用shadcn-vue1.0.3版本配置方式以对应版本的文档为准。前置要求Node.js 环境建议 LTS 版本npm 可用对 Vue 3 组合式 APIscript setup与 TypeScript 有基本了解目标项目为 Vite 脚手架创建的新项目本指南不会处理已有项目的迁移冲突问题。第一步创建 Vite 项目使用 Vite 官方脚手架创建一个 Vue TypeScript 模板项目npm create vitelatest my-vue-app --template vue-ts该命令会生成vue-ts模板项目。仓库中的官方 Vite 模板templates/vite/package.json展示了安装完成后典型的依赖结构vue^3.5.x作为运行时依赖开发依赖包含vite^6.0.0、vitejs/plugin-vue、typescript、vue-tsc、tailwindcss与tailwindcss/vite均指向 ^4.0.0。进入项目目录后即可进行后续步骤cd my-vue-app第二步安装并接入 Tailwind CSS v4安装 Tailwind CSS 及其 Vite 插件npm install tailwindcss tailwindcss/vite然后将src/style.css或src/assets/index.css取决于脚手架生成的文件名中的全部内容替换为如下单行导入import tailwindcss;在 Tailwind v4 中这条指令即完成 CSS 层的初始化不再需要tailwind.config.js与tailwind指令。仓库官方模板 templates/vite/src/assets/index.css 的内容正是这一行并在 templates/vite/src/main.ts 中通过import ./assets/index.css引入全局样式——你的项目也应保证入口文件main.ts导入该样式文件。第三步编辑 tsconfig.json 与 tsconfig.app.json当前版本的 Vite 将 TypeScript 配置拆分为多个文件其中两个需要修改目的是让 TypeScript 编译器与 IDE 识别/*路径别名。tsconfig.json在compilerOptions中添加baseUrl与paths{ files: [], references: [ { path: ./tsconfig.app.json }, { path: ./tsconfig.node.json } ], compilerOptions: { baseUrl: ., paths: { /*: [./src/*] } } }tsconfig.app.json在tsconfig.app.json的compilerOptions中同样加入路径映射以便 IDEVSCode / Volar正确解析导入{ compilerOptions: { // ... baseUrl: ., paths: { /*: [ ./src/* ] } // ... } }仓库官方模板 templates/vite/tsconfig.json 采用略有差异但等效的写法未显式写baseUrl仅配置paths: { /*: [./src/*] }实际效果一致所有以/开头的导入都会解析到src/目录。第四步更新 vite.config.ts路径别名同时需要让 Vite 构建器认识否则运行时会报解析错误。官方文档提供两种方案任选其一。方案 A使用resolve.alias首先安装 Node.js 类型声明npm install -D types/node然后编写vite.config.tsimport path from node:path import tailwindcss from tailwindcss/vite import vue from vitejs/plugin-vue import { defineConfig } from vite export default defineConfig({ plugins: [vue(), tailwindcss()], resolve: { alias: { : path.resolve(__dirname, ./src), }, }, })注意由于 Vite 配置默认以 ESM 方式加载__dirname在部分环境下不可用。仓库官方模板 templates/vite/vite.config.ts 使用了更稳妥的写法用import.meta.url计算路径import { fileURLToPath, URL } from node:url // ... alias: { : fileURLToPath(new URL(./src, import.meta.url)), }方案 B使用vite-tsconfig-paths安装该插件让 Vite 直接复用tsconfig中的路径映射无需手写 aliasnpm install -D vite-tsconfig-pathsimport tailwindcss from tailwindcss/vite import vue from vitejs/plugin-vue import { defineConfig } from vite import tsconfigPaths from vite-tsconfig-paths export default defineConfig({ plugins: [vue(), tailwindcss(), tsconfigPaths()], })两种方案的效果等价推荐方案 B单一维护tsconfig.json中的映射即可减少重复配置。第五步运行 CLI 初始化完成上述配置后运行 shadcn-vue 初始化命令npx shadcn-vuelatest init命令会向你提出几个问题用于生成根目录下的components.json配置文件例如Which color would you like to use as base color? › Neutral从 CLI 源码packages/cli/src/commands/init.ts可以看出初始化交互大致覆盖以下决策项问题说明常见选项TypeScript 是否启用推荐开启yes/no组件库 base底层 headless 组件库reka视觉风格 style组件外观风格vega推荐、nova、maia、lyra、mira等图标库 iconLibrary组件默认图标来源lucide、tabler、hugeicons、phosphor、remixicon字体 font主题字体inter、figtree、geist等基础色 baseColor主题基色neutral、gray、zinc、stone、slate全局 CSS 文件位置Tailwind 样式入口默认为src/style.css之类是否使用 CSS 变量主题变量化yes/nocomponents / utils 别名导入别名默认/components、/lib/utils初始化完成后CLI 会执行预检preflight、写出components.json并安装基础样式与必要依赖如class-variance-authority、clsx、tailwind-merge、lucide-vue-next、tw-animate-css等详见 deprecated/www/src/content/docs/installation/manual.md 中手动安装一节。init命令还支持大量非交互参数便于 CI 或脚本化使用同样来自 init.ts 的 commander 定义npx shadcn-vuelatest init --defaults # 使用默认配置 npx shadcn-vuelatest init -y # 跳过确认提示 npx shadcn-vuelatest init --base-color slate # 直接指定基础色 npx shadcn-vuelatest init --style nova # 直接指定风格 npx shadcn-vuelatest init --icon-library tabler npx shadcn-vuelatest init --font geist npx shadcn-vuelatest init --no-css-variables # 不使用 CSS 变量 npx shadcn-vuelatest init --cwd ./my-app # 指定工作目录第六步添加并引用组件初始化成功后即可添加第一个组件npx shadcn-vuelatest add button该命令会将Button组件源码复制到你的项目默认落在src/components/ui/button并自动补齐组件所需的依赖。从 packages/cli/src/commands/add.ts 的实现可见add支持一次性添加多个组件、指定--cwd工作目录、--overwrite覆盖已有文件等选项也可以直接传组件名、注册表 URL 或本地路径。之后在任意 Vue 组件中导入使用script setup langts import { Button } from /components/ui/button /script template div ButtonClick me/Button /div /templateButton是一个原生button的包装组件支持variant默认、destructive、outline、secondary、ghost、link 等与size等 props可直接套用 Tailwind 类进行覆盖。从源码看安装链路init 与 add 做了什么理解底层流程有助于排查安装问题。以仓库源码为据入口注册CLI 入口 packages/cli/src/index.ts 使用commander注册了init、add、apply、diff、docs、view、search、migrate、info、build、mcp等命令npx shadcn-vuelatest即解析执行其中之一。init 流程init.ts 的runInit先执行preFlightInit预检项目状态若目录为空可选择基于内置模板nuxt、vite、astro、laravel直接创建项目随后解析/交互生成配置写回components.json最后调用addComponents安装基础样式与用户指定的组件。若components.json已存在CLI 会先备份再写入失败时自动回滚避免破坏既有配置。add 流程add.ts根据传入的组件名/URL 从注册表获取 registry 条目解析其依赖与文件再写入项目对应目录并更新样式/依赖。从代码结构还可以推断style决定组件变体与外观仓库中apps/v4/styles/下存在多套风格目录base决定底层交互原语当前为rekaiconLibrary决定图标来源——这些都在初始化时固化进components.json之后add命令会依据该文件决定拉取哪个版本的组件。常见问题与后续路线路径别名报错确认tsconfig.json、tsconfig.app.json与vite.config.ts三处/*映射一致方案 A 时尤其注意样式未生效确认src/style.css只包含import tailwindcss;且已在main.ts中导入Tailwind v3 用户请锁定shadcn-vue1.0.3不要使用本指南的 Tailwind v4 配置想深入主题定制初始化生成的是基于 CSS 变量的主题体系可参考手动安装文档 deprecated/www/src/content/docs/installation/manual.md 中的全局样式变量与theme inline用法理解--background、--primary、--radius等 token 如何映射到 Tailwind 颜色与圆角。安装完成后就可以持续用npx shadcn-vuelatest add component按需添加组件并配合 手动安装指南 或仓库内 Nuxtdeprecated/www/src/content/docs/installation/nuxt.md、Astrodeprecated/www/src/content/docs/installation/astro.md、Laraveldeprecated/www/src/content/docs/installation/laravel.md等框架的安装文档按需扩展。【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考