shadcn-svelte CLI 完全指南init / add / apply / update / registry build 命令详解与 components.json 配置实战【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte本指南以 shadcn-svelte 仓库中的官方 CLI 参考文档skills/shadcn-svelte/cli.md为核心骨架系统讲解五个核心命令的完整参数、代理配置、设计系统预设机制以及components.json中与 Agent 协作相关的关键字段。读者将掌握从项目初始化、组件安装、预设应用、组件升级到自定义 registry 构建的完整 CLI 工作流并能读懂 CLI 底层实现源码位于packages/cli/src在实际项目中准确、安全地使用该工具。前置须知运行方式与使用原则在使用任何命令前请记住两条铁律始终使用项目自身的包管理器运行 CLI。命令形如npx shadcn-sveltelatest、pnpm dlx shadcn-sveltelatest或bunx --bun shadcn-sveltelatest具体选哪个取决于项目package.json中的packageManager字段或锁文件。CLI 会自动检测包管理器不存在--package-manager之类的标志。只使用文档列出的标志。不要凭空猜测或发明参数——如果某个标志未在文档中出现它就并不存在。否则可能静默地不被解析甚至报错。所有命令都要求目标目录存在如果--cwd指向的路径不存在CLI 会直接抛出错误并终止参见 init 命令源码 中对existsSync(cwd)的检查。Commands五个核心命令init— 初始化已有项目npx shadcn-sveltelatest init [options]init负责在已存在的项目SvelteKit、Vite 等中完成初始化安装依赖、添加cn工具函数、创建components.json、配置 CSS 变量。请在项目根目录执行。从源码看init的完整执行链init/index.ts为解析选项 → 校验 cwd 存在 → 解码--preset→ 运行 preflight 检查 → 加载/检测既有components.json→ 交互式确认预设、全局 CSS 路径与导入别名 → 写入配置 → 从 registry 拉取初始化条目并安装依赖。完整参数表标志短标志说明默认值--preset preset—来自文档站设计系统构建器的编码预设字符串—-c, --cwd path-c工作目录当前目录-o, --overwrite—覆盖已有文件false--no-deps—不添加也不安装依赖—--skip-preflight—忽略 preflight 检查并继续false--base-color name—基础色neutral、stone、zinc、mauve、olive、mist、taupe—--css path—全局 CSS 文件路径—--components-alias path—组件的导入别名—--lib-alias path—lib 的导入别名—--utils-alias path—utils 的导入别名—--hooks-alias path—hooks 的导入别名—--ui-alias path—UI 组件的导入别名—--proxy proxy—通过指定代理拉取 registry 条目基于环境变量--design-system-url—可选的设计系统 URL参见文档站 / 预设构建器—-h, --help-h显示帮助—版本前提Tailwind v4 Svelte v5这是最容易踩坑的一点。init命令带有 preflight 检查preflight.ts它读取项目中的svelte与tailwindcss依赖版本并做语义化版本校验checkInitDependenciesTailwind CSS v4 Svelte v5正常通过。Tailwind v3 Svelte v5直接报错提示需先升级到 Tailwind v4或改用shadcn-svelte1.0.0-next.10支持 Tailwind v3 的初始化。Tailwind v3 Svelte v4报错提示改用shadcn-svelte0.14。其他组合统一提示该 CLI 版本要求 Tailwind CSS v4 与 Svelte v5。除非显式传入--skip-preflight否则上述任一失败都会中断初始化。这也解释了文档中 Runinitfrom the root of your project 的用意——preflight 依赖项目根目录下的依赖信息。别名校验与自动目录创建--*-alias系列标志并非直接写死CLI 会基于tsconfig/jsconfig校验导入别名是否有效validateOptions并在写入配置后自动创建各别名对应的目录runInit。一个值得注意的细节若utils别名形如/lib/utilsCLI 会假定其为文件并剔除末尾的utils来定位目录同时不会为utils强制建目录。样式变更时的组件重装提示如果init检测到已有配置的 style/menuColor/menuAccent 与所选预设不一致styleChanged会询问用户是否覆盖现有组件以应用新样式runInit。这正是文档中-o, --overwrite与源码中新增的--reinstall选项的来源源码中-o, --overwrite已标记为deprecated建议改用--reinstall见 init/index.ts 的.hideHelp()与告警逻辑。add— 添加组件npx shadcn-sveltelatest add [options] [components...]从已配置的 registry 添加组件。参数可以是 registry 索引中的组件名也可以是指向某个 registry JSON 条目的 URL。不传任何组件名时CLI 会以交互式多选列表让你挑选组件。源码中的实际行为add/index.ts拉取 registry 索引过滤出registry:ui类型的条目供选择--all时全量安装这些 UI 组件交互列表会为每个组件标注还会一并添加的依赖未传-y时会二次确认依赖安装默认开启可用--no-deps跳过此时会列出被跳过的依赖清单。注意add要求项目已存在components.json否则会提示先运行initadd/index.ts。完整参数表标志短标志说明默认值-c, --cwd path-c工作目录当前目录--no-deps—跳过添加与安装包依赖—--skip-preflight—忽略 preflight 检查并继续false-a, --all—安装全部 UI 组件false-y, --yes—跳过确认提示false-o, --overwrite—覆盖已有文件false--proxy proxy—通过指定代理拉取组件基于环境变量-h, --help-h显示帮助—安全提示通过 URL 添加组件是显式行为。如果组件来自未知来源务必先确认 registry URL 或条目再执行add参见 SKILL.md 中的 Workflow 第 7 条。-o, --overwrite会覆盖已有文件在可能破坏刻意修改时不要擅自使用。apply— 向已有项目应用预设npx shadcn-sveltelatest apply [options]apply把设计系统预设应用到已经完成初始化的项目更新components.json中的预设设置按新样式重装已有组件utils除外并安装所需的额外依赖。使用--only theme或--only font可以只应用预设的一部分而不重装 UI 组件。预设代码可在设计系统构建器shadcn-svelte.com/create获取。源码实现apply/index.ts印证了文档描述它先把预设中的iconLibrary、menuColor、menuAccent、style、tailwind.baseColor写回配置然后以skipExisting: true与forceStylesheet: true调用底层addRegistryItems只覆盖样式相关文件若--only theme则跳过依赖安装onlyApplyTheme分支直接return。完整参数表标志短标志说明默认值--preset preset—编码的设计系统预设字符串必填—--only [parts]—只应用预设中的theme或font—-c, --cwd path-c工作目录当前目录-y, --yes-y不确认直接覆盖已有文件false-s, --silent-s静默输出false--skip-preflight—忽略 preflight 检查并继续false--proxy proxy—通过指定代理拉取 registry 条目基于环境变量-h, --help-h显示帮助—apply要求项目已有components.json未初始化请先运行init且--preset是必填项——两者缺失都会直接报错apply/index.ts。update— 更新已安装的组件npx shadcn-sveltelatest update [options] [components...]update从 registry重新拉取并应用项目里已存在组件的内容用于将本地组件同步到 registry 的最新版本。运行shadcn-svelte update --help可查看全部选项。完整参数表标志短标志说明默认值-c, --cwd path-c工作目录当前目录--skip-preflight—忽略 preflight 检查并继续false--no-deps—跳过添加与安装包依赖—-a, --all—更新所有已安装组件false-y, --yes—跳过确认提示false--proxy proxy—通过该代理拉取基于环境变量-h, --help-h显示帮助—务必在更新前提交你的工作——覆盖操作具有破坏性若你对组件做过定制修改更新后需要处理合并冲突。源码层面的更新流程update/index.ts非常值得了解读取 registry 索引扫描项目已安装的组件project.getComponents未指定组件且未加--all时弹出多选列表会标注同时更新的依赖解析并拉取对应 registry 条目逐个运行转换器管线transformerstransformImports导入别名重写、transformIcons图标库适配、transformMenu、transformFont字体标记、以及非 TS 项目下的transformStripTypes剥离类型合并css/cssVars并通过transformCss更新全局样式表transform-css.ts最后汇总依赖清单安装或提示并警告组件中不再被使用的遗留文件提示你可能需要手动删除。registry build— 构建自定义 registrynpx shadcn-sveltelatest registry build [options] [registry]面向registry 作者的命令读取一个registry.json把其中声明的条目逐个打包为可供分发使用的 registry JSON 文件。默认输入./registry.json默认输出./static/r。完整参数表标志短标志说明默认值-c, --cwd path-c工作目录当前目录-o, --output path-oJSON 文件输出目录./static/r-h, --help-h显示帮助—构建流程build.ts的关键能力自动依赖解析若条目未显式声明dependencies/devDependencies会扫描源文件 import 自动推断types/*类型包自动归入 devDependencies也支持通过overrideDependencies覆盖解析结果。别名标准化transformAliases会把源码中的$lib/...等路径占位符替换为统一的$UI$/$LIB$等占位符build.ts这样生成的 registry JSON 能被不同别名配置的项目复用。本地依赖引用local:stepper形式的 registry 依赖会被转换为相对路径./stepper.jsontransformLocal。输出包含一个index.jsonregistry 索引以及每个条目一个name.json。出站请求与代理CLI 拉取 registry 条目时会发起网络请求支持两种代理方式环境变量若设置了HTTP_PROXY或http_proxy请求会自动遵循。从源码看get-env-proxy.ts实际读取顺序为HTTP_PROXY→http_proxy→HTTPS_PROXY→https_proxy→npm_config_proxy→npm_config_https_proxy。--proxy标志可在init、add、apply、update上显式传入。运行时会把该值写入process.env.HTTP_PROXY并打印提示如 add/index.ts。HTTP_PROXYproxy-url npx shadcn-sveltelatest init设计系统预设Presets设计系统选项风格 style、主题 theme、图标 icons、字体 fonts 等可被编码为一串预设字符串来源于文档站的设计系统构建器shadcn-svelte.com/create随后通过 CLI 使用新项目把预设字符串传给initinit --preset string。已有项目用apply --preset string更新配置、重装已安装组件样式并安装新依赖。从源码看预设字符串采用 Base62 编码preset/index.ts 导出encodePreset/decodePreset/isPresetCode/isValidPreset等。init与apply都通过decodePreset解析字符串解析失败会给出警告或直接报错init/index.ts。内部机制上CLI 会把编码后的预设拼进 registry 的/init?preset...端点 URL再作为 registry 条目拉取init/index.ts从而实现一次编码、处处复现的整套设计系统配置。components.json— 对 Agent 有用的字段components.json是 CLI 的配置中枢也是 AI Agent 理解项目 shadcn-svelte 装配情况的首要入口。以下字段对 Agent 尤其关键字段 / 路径含义tailwind.css全局 CSS 文件路径Tailwind 入口 / 主题变量所在tailwind.baseColor基础调色板初始化后不可更改aliases.*导入别名必须与svelte.config.js/tsconfig的 paths 一致registry基础 registry URL默认https://shadcn-svelte.com/registrystyle注册的样式名如nova、vega等iconLibrary图标集键lucide、tabler等——决定生成的导入语句typescript是否使用 TS以及可选的自定义配置路径其中的解析路径包括tailwindCss、ui、components等由 CLI 根据components.json与文件系统计算得出写入resolvedPaths参见 config/schema.ts。因此需要当前装了什么的快照时应读取components.json并列出 UI 目录而不是依赖单独的 info 命令。对照文档站的完整 schemadocs/content/components-json.md与源码默认值config/schema.ts可补充以下字段语义aliases子字段lib默认$lib、utils默认$lib/utils、hooks默认$lib/hooks对应 Svelte 5 中以.svelte.ts/.svelte.js结尾的响应式文件、components默认$lib/components、ui默认$lib/components/ui。alias 需与svelte.config.js中的 alias 配置一致CLI 才能把组件写到正确位置。typescript可以是布尔值也可以是{ config: path/to/tsconfig.custom.json }对象用于指定名称或位置不同的自定义 TS 配置components-json.md。false时更新流程会额外执行transformStripTypes剥离类型。style/iconLibrary/menuColor/menuAccent四个设计系统维度均在 schema 中定义了合法枚举config/schema.tsiconLibrary直接决定生成的 import 来自lucide/svelte还是tabler/icons-svelte等包。registry默认官方 registry可固定到某个预览版本或自建 forkcomponents-json.md。Agent 实战工作流速查结合 SKILL.md 的 Workflow 与 CLI 文档推荐的标准流程获取项目上下文读取根目录components.json必要时列出aliases.ui解析出的目录以确认已安装组件。先查已装组件执行add前先列出ui目录——不要重复添加已存在组件也不要导入尚未添加的组件。发现组件npx shadcn-sveltelatest add不带参数走交互列表或查阅组件文档。安装或更新add name或 registry URL刷新已有组件用update更新后建议用git diff审查变更。修正 URL 添加项的导入从自定义 registry URL 添加后检查是否有硬编码路径与项目aliases不符改写为components.json中的ui/lib别名。审查添加结果读取新增文件核对组合结构Group、Title、校验属性等并让图标导入与iconLibrary对齐。# 初始化项目 npx shadcn-sveltelatest init # 携带文档站预设字符串初始化 npx shadcn-sveltelatest init --preset code # 添加组件不带名称时进入交互选择 npx shadcn-sveltelatest add npx shadcn-sveltelatest add button card dialog npx shadcn-sveltelatest add --all # 更新已安装组件 npx shadcn-sveltelatest update button npx shadcn-sveltelatest update --all --yes # 构建自定义 registry面向 registry 作者 npx shadcn-sveltelatest registry buildRegistry 默认地址https://shadcn-svelte.com/registry如需覆盖可在components.json中修改registry字段。小结shadcn-svelte CLI 的五个命令构成了完整的项目生命周期管理init建立配置基础受 Tailwind v4 Svelte v5 版本前提约束add按需安装组件apply让预设变更平滑落到已有项目支持--only theme|font精细控制update保持已装组件与 registry 同步registry build则支撑自定义组件生态的构建与分发。配合代理配置、预设编码机制与components.json的语义理解无论是人工操作还是 AI Agent 自动化都能在准确、可预测的前提下完成组件的安装、升级与样式切换。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考