UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载shadcn-vue 的 Registry Directory 是官方文档中集中展示社区组件注册表的入口页它把由第三方维护、且已内置进 CLI 的注册表以可搜索列表的形式呈现并允许通过一行add命令把任意注册表中的组件装进你的 Nuxt、Vite 或任意 Vue 项目。本文将以该目录页为核心结合本仓库源码目录页组件、注册表元数据与 CLI 解析逻辑完整讲解如何发现社区注册表、理解registry/component安装语法的底层解析规则以及如何把目录页链接到的 Getting Started / Examples / registry.json / FAQ 等文档串成一条自建注册表的分发链路。什么是 Registry Directoryapps/v4/content/docs/directory/index.md是 shadcn-vue 文档站点中 “Directory目录” 页面的内容源。它的定位非常明确集中展示社区注册表community registries。文档开篇即点出核心事实这些注册表已内置进 CLI无需任何额外配置。要添加组件运行npx shadcn-vuelatest add registry/component。也就是说目录页上的每个注册表都对应一个namespace前缀用户不需要手动在components.json里注册CLI 开箱即可解析。这个零配置内置的特性是由 CLI 源码中的两个常量支撑的packages/cli/src/registry/constants.ts 中的BUILTIN_REGISTRIES定义了默认注册表shadcn其 URL 模板为${REGISTRY_URL}/styles/{style}/{name}.json同文件中的REGISTRY_URL默认指向${SHADCN_VUE_URL}/rSHADCN_VUE_URL默认为https://shadcn-vue.com可通过环境变量覆盖。目录页还内置了与本主题强相关的安全提示这一点在使用社区注册表时尤其值得留意社区注册表由第三方开发者维护。安装时务必审查代码确保其符合你的安全与质量标准。这句话与 CLI 文档中的安全建议一脉相承详见下文安全须知一节也是阅读本目录页时最重要的心智模型目录页只是发现入口代码审查责任仍在使用者自己。目录页的数据来源RegistryEntry 与内置种子注册表目录页的列表并非硬编码在文档里而是由文档中的::registry-directory短代码component渲染出来。该组件位于 apps/v4/components/content/RegistryDirectory.vue数据则来自 apps/v4/registry/registries.ts 中的registries数组。registries.ts定义了每个注册表条目的数据结构RegistryEntryexport interface RegistryEntry { /** Namespace key, e.g. acme. Must match /^[a-z0-9][\w-]*$/i */ name: string /** Display name, e.g. Acme UI */ title: string description: string /** URL template; MUST contain the {name} placeholder, e.g. https://acme.com/r/{name}.json */ url: string /** Public homepage / docs link for the registry */ homepage: string author?: string /** Inline SVG logo markup, rendered with fill/stroke inherited from the foreground color */ logo?: string /** Free-form tags used for client-side filtering, e.g. [ui, blocks] */ tags?: string[] }这里有几个值得注意的约定name是namespace形式必须匹配^[a-z0-9][\w-]*$/i的命名规范这与 CLI 端解析registry/component的正则见下文安装语法的底层解析完全对应url是注册表的 URL 模板必须包含{name}占位符例如https://acme.com/r/{name}.jsonlogo是内联 SVG 字符串渲染时继承前景色fill/stroke由currentColor决定目录页中统一以grayscale灰度显示。仓库中的种子条目真实世界的策展仍在持续 PR 维护中源码注释明确标注了这一点包括nametitleurl 模板tagsshadcnshadcn-vuehttps://shadcn-vue.com/r/styles/{style}/{name}.jsonui, blocks, chartsinspira-uiInspira UIhttps://registry.inspira-ui.com/{name}.jsonui, animations, effectsmapcnMapcnhttps://mapcn-vue.geoql.in/r/{name}.jsonui, mapsai-elementsAI Elements Vuehttps://registry.ai-elements-vue.com/{name}.jsonui, ai, chatbot, elementselevenlabs-uiElevenLabs UI Vuehttps://registry.elevenlabs-ui-vue.com/{name}.jsonui, ai, agent, audio从源码结构看tags字段目前用于目录页的客户端过滤而shadcn作为官方注册表与 CLI 的BUILTIN_REGISTRIES保持一致其余为社区注册表。目录页的交互设计搜索、分页与 Add 命令RegistryDirectory.vue把一份静态列表做成了完整的交互界面理解它的行为有助于你在使用目录页时快速定位目标组件搜索过滤顶部的搜索框对name、title、description三个字段做归一化匹配小写、去空格、去输入后通过watchDebounced250ms 防抖同步到 URL 的q查询参数可分享搜索状态分页每页 10 条PAGE_SIZE 10页码通过page查询参数驱动并实现了与 shadcn-ui 目录一致的省略号分页逻辑首页/末页始终可见省略号仅在隐藏超过一页时出现Add 对话框点击某条注册表的 Add 按钮会弹出 Dialog/Drawer移动端用 Drawer展示针对不同包管理器的安装命令。命令模板在 apps/v4/components/content/RegistryDirectory.vue 中生成const commands computedRecordstring, string | null(() { if (!selectedRegistry.value) return null const item ${selectedRegistry.value.name}/[component] return { pnpm: pnpm dlx shadcn-vuelatest add ${item}, npm: npx shadcn-vuelatest add ${item}, yarn: yarn dlx shadcn-vuelatest add ${item}, bun: bunx --bun shadcn-vuelatest add ${item}, } })也就是说目录页最终产出的就是形如npx shadcn-vuelatest add inspira-ui/[component]的一行命令——这正好对应文档正文给出的通用语法npx shadcn-vuelatest add registry/component。安装语法的底层解析CLI 如何理解 namespace目录页提供的命令能否生效取决于 CLI 对registry/component字符串的解析。核心逻辑在 packages/cli/src/registry/parser.ts// Valid registry name pattern: namespace where namespace is alphanumeric with hyphens/underscores const REGISTRY_PATTERN /^(a-z0-9?)\/(.)$/i export function parseRegistryAndItemFromString(name: string) { if (!name.startsWith()) { return { registry: null, item: name } } const match name.match(REGISTRY_PATTERN) if (match) { return { registry: match[1], item: match[2] } } return { registry: null, item: name } }解析规则可以总结为字符串必须以开头注册表名必须匹配a-z0-9?即小写字母/数字开头结尾中间允许字母数字、连字符、下划线以/分隔注册表名与组件名组件名本身可以包含/例如acme/forms/login表示名为forms/login的注册表项而不是嵌套的 registry.json这一点在 CLI 文档的 Notes 中有明确说明不满足上述条件的字符串例如不带的button会被当作普通组件名回退到默认的shadcn官方注册表解析。解析出namespace后CLI 会把它映射到对应的 URL 模板。命名空间发现逻辑位于 packages/cli/src/registry/namespaces.tsresolveRegistryNamespaces会递归遍历所有待安装组件及其registryDependencies把非内置不在BUILTIN_REGISTRIES中的命名空间收集起来用于后续批量解析即便某个命名空间未在components.json中配置抛出RegistryNotConfiguredError它仍会被记录并继续处理其他依赖尽可能多地发现命名空间。从目录到自建Registry 文档体系导航目录页的下半部分是 Documentation 区块它把如何运行你自己的代码注册表这条路径完整铺开。原文明确指出你可以使用shadcn-vueCLI 运行你自己的代码注册表。运行你自己的注册表可以让你把自定义组件、hooks、页面、配置、规则及其他文件分发给任意项目。文档区块以五张卡片链接到注册表文档的五个核心页面它们在仓库中的对应文件如下Getting Started设置并构建你自己的注册表 → apps/v4/content/docs/registry/getting-started.mdExamples注册表条目示例与配置 → apps/v4/content/docs/registry/examples.mdregistry.jsonregistry.json 的 schema 规范 → apps/v4/content/docs/registry/registry-json.mdregistry-item.json注册表条目的 schema 规范 → apps/v4/content/docs/registry/registry-item-json.mdFAQ常见问题 → apps/v4/content/docs/registry/faq.md这套文档体系与目录页共同构成完整的注册表生态目录页解决发现别人的注册表Documentation 解决让别人发现你的注册表。registry.json注册表的清单文件根据 apps/v4/content/docs/registry/registry-json.mdregistry.json用于定义你的自定义组件注册表最简结构如下{ $schema: https://shadcn-vue.com/schema/registry.json, name: shadcn, homepage: https://shadcn-vue.com, items: [ { name: hello-world, type: registry:block, title: Hello World, description: A simple hello world component., files: [ { path: registry/new-york/HelloWorld/HelloWorld.vue, type: registry:component } ] } ] }各字段的含义与用途$schema声明 registry.json 遵循的 JSON Schema 地址用于编辑器校验name注册表名称用于 data attribute 等元数据例如acmehomepage注册表主页同样用于元数据items注册表条目数组每一项都必须实现 registry-item schema 规范registry:block、registry:component等类型的定义见 registry-item-json.md。需要说明的是registry.json只在用shadcn-vueCLI 构建注册表时才必须提供如果使用其他构建系统只要产出符合 registry-item schema 的合法 JSON 文件即可。自建注册表的完整链路把 getting-started.md 串起来看从零搭建一个可被目录页生态消费的注册表需要经过以下阶段创建组件在项目里按registry/[STYLE]/[NAME]目录结构放置组件例如registry/new-york/HelloWorld/HelloWorld.vue若使用自定义目录记得在tailwind.config.ts的content中声明例如content: [./registry/**/*.{js,ts,jsx,tsx,vue}]登记条目在registry.json的items中为每个组件填写name、type、title、description、files每个文件必须给出相对项目根目录的path与文件type构建安装 CLInpm install shadcn-vuelatest注意build命令目前仅存在于shadcn-vuecanary版本在package.json中添加registry:build: shadcn-vue build脚本并运行npm run registry:build默认在public/r目录生成hello-world.json这类 JSON 文件可用--output更改输出目录托管Nuxt 项目直接npm run dev即可在http://localhost:3000/r/[NAME].json访问要让其他开发者可用需部署到公开 URL鉴权可选CLI 未内置 auth推荐在注册表服务端处理授权常见做法是使用token查询参数如http://localhost:3000/r/hello-world.json?token[SECURE_TOKEN_HERE]token 无效时返回 401CLI 会据此向用户展示提示官方同时强调 token 需要加密并设置过期时间安装验证npx shadcn-vuelatest add http://localhost:3000/r/hello-world.json即可从托管 URL 安装。组件条目的编写准则getting-started 的 Guidelines 一节给出了一组硬性约定是注册表条目能被 CLI 正确消费的前提条目必须放置在registry/[STYLE]/[NAME]目录下[STYLE]可以是任意名称但必须嵌套在registry目录下块定义block必须包含name、description、type、files四个属性所有注册表依赖必须列在registryDependencies中——它可以是注册表内组件名如input、button、card也可以是注册表条目 URL如http://localhost:3000/r/editor.json所有 npm 依赖必须列在dependencies中可用nameversion指定版本如zod^3.20.0组件内部导入必须始终使用/registry路径例如import { HelloWorld } from /registry/new-york/hello-world/hello-world文件尽量按components、hooks、lib目录归类。通过 examples 深化条目的表达能力examples.md 展示了注册表条目远超一个组件的表达能力这在设计自己的注册表时非常实用registry:style类型的条目可以在npx shadcn-vue init时批量安装依赖、追加registryDependencies包括远程注册表 URL、写入cssVars如font-sans、自定义brand色通过extends: none还可以不继承 shadcn-vue 默认样式从零定义整套 CSS 变量registry:theme条目用于覆盖主题色支持oklch()等现代颜色语法registry:block条目可以包含files数组每个文件可指定target如pages/login/index.vue精确控制安装落点也可仅靠registryDependencies引用官方Login01块并覆盖其中的button、input、label等原语条目支持自定义 CSSlayer base、layer components、自定义工具类utility、自定义动画同时定义keyframes与cssVars.theme中的--animate-*以及 Tailwind 主题变量spacing、breakpoint-*等。FAQfaq.md则进一步给出复杂条目的完整形态一个条目可以同时安装页面registry:page、多个组件registry:component、组合式函数registry:hook、工具函数registry:utils和配置文件registry:file新增 Tailwind 颜色需同时更新cssVars与tailwind.config.theme.extend.colors安装后即可使用bg-brand、text-brand-accent等工具类新增动画同理需同时声明keyframes与animation。无需自建托管直接从 GitHub 安装注册表对于已托管在公开 GitHub 仓库且根目录存在registry.json的注册表CLI 还提供了一条零配置安装路径目录页文档虽然没有展开但其背后的机制同样属于注册表分发主题这里一并补充npx shadcn-vuelatest add owner/repo/hello-world其实现位于 packages/cli/src/registry/github.ts。关键机制是commit 固定commit pinningCLI 先通过git ls-remote解析仓库默认分支得到 commit SHAresolveGitHubRef然后从raw.githubusercontent.com按owner/repo/sha/path拉取registry.json与每个files[].path。由于所有文件都来自同一个已解析的 commit即使安装过程中分支发生移动也不会拿到半更新的组件。仓库中的 ref 缓存与文件缓存都会在进程生命周期内保留URL 含 commit SHA天然不可变。该机制还支持更多用法固定分支、标签或 commitadd owner/repo/hello-world#main、#v1.2.0或完整的 40 位 commit SHA名称冲突时分支优先于标签注解标签annotated tag会解析到其指向的 commit列出仓库发布的内容npx shadcn-vuelatest search owner/repo注册命名空间免输仓库名在components.json中把acme映射到 URL 模板https://acme.com/r/{name}.json之后即可用npx shadcn-vuelatest add acme/hello-world。注意命名空间映射的是托管注册表 URL 模板而非 GitHub 仓库因此它是 GitHub 安装方式的替代方案而非简写。几点限制值得注意条目名可以包含斜杠owner/repo/forms/login表示名为forms/login的条目仓库必须公开raw.githubusercontent.com不服务私有仓库私有场景应改用带鉴权的托管注册表解析 ref 依赖本机git命令git ls-remote这正是它能找到默认分支而非猜测main的原因registryDependencies仍按常规方式解析——裸名称如button回落到默认的shadcn注册表因此信任一个仓库也意味着信任它所依赖的一切。安全须知把 add 当作 npm install 对待目录页文档与 GitHub 安装文档反复强调同一条安全原则安装注册表条目会在你的机器上运行第三方代码——一个条目可以声明 npmdependencies由你的包管理器安装并执行其安装脚本也可以向项目写入文件。GitHub 形式的安装尤其需要警惕因为它无需任何配置README 里一行命令就足以让你从未看过的仓库安装东西。官方给出的建议是对待npx shadcn-vuelatest add owner/repo/item应与对待npm install owner-repo一样谨慎——如果不清楚仓库归属先阅读注册表内容。作为防线CLI 会拒绝path与target值为绝对路径或包含..逃逸项目目录的条目——无论是对你请求的条目本身还是在文件写入时。但官方明确说明这只是一道针对失误和恶意条目最常见手段的防护不是沙箱。因此目录页开篇那句安装时务必审查代码应当成为使用任何社区注册表时的默认动作。小结从apps/v4/content/docs/directory/index.md出发我们可以勾勒出 shadcn-vue 注册表生态的完整图景发现侧Directory 目录页RegistryDirectory.vue registries.ts以可搜索、可分享、跨包管理器命令复制的形式呈现内置社区注册表是用户进入生态的第一站解析侧CLI 以REGISTRY_PATTERN解析namespace/component通过BUILTIN_REGISTRIES与命名空间发现逻辑parser.ts、namespaces.ts完成 URL 模板映射并支持 URL、GitHub 仓库commit 固定与components.json命名空间三种安装来源生产侧Documentation 五篇文档getting-started、examples、registry-json、registry-item-json、faq给出了从registry.json清单、条目 schema、构建脚本到托管鉴权的完整自建链路。无论你是想用别人现成的组件还是把自己沉淀的组件分发给团队与社区目录页及其背后的 CLI 机制都提供了统一的入口前者只需一行add命令后者则可以从registry.json起步最终让自家的注册表出现在目录之中。赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐Comp AI CRM 中的 shadcn Registry 编写与地址解析从源注册表到 CLI 分发Comp AI CRM 中的 shadcn Registry 编写与地址解析从源注册表到 CLI 分发 Comp AI CRMcrm48/crm 镜像仓库后端前端CRM人工智能AI Agent使用 shadcn-vue CLI 搭建自己的组件 Registry从 registry.json 定义到发布安装全流程使用 shadcn vue CLI 搭建自己的组件 Registry从 registry.json 定义到发布安装全流程 组件 Registry 是 shadUI组件前端shadcn-vue registry.json 完全指南搭建并发布你自己的 Vue 组件注册表shadcn vue registry.json 完全指南搭建并发布你自己的 Vue 组件注册表 registry.json 是 shadcn vue 生态中UI组件前端上一篇Cargo 输出显示控制选项完全指南-v/--verbose、-q/--quiet 与 --color 的用法、配置与底层实现下一篇IcemacOS 菜单栏管理图标再多也不怕创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
