@mar7th/march7th-ui-vue

基于 shadcn-vue 二次开发的 Vue 3 组件库，组件采用单一源码结构，同时支持 npm 引入、源码复制、独立开发中心和 VitePress 文档站。

在线文档与组件演示：vue-ui.march7th.online

AI 开发上下文：llms.txt

安装使用

pnpm add @mar7th/march7th-ui-vue

项目需要使用 Vue 3。npm 包已经包含构建后的组件样式，在应用入口引入即可：

import "@mar7th/march7th-ui-vue/style.css"

组件库依赖 @mar7th/march7th-theme 提供基础 Token、shadcn 变量映射和主题控制器；安装组件库时会自动安装，无需在业务项目重复声明依赖。

可以从包根入口或组件子路径引入：

import { Button, Input } from "@mar7th/march7th-ui-vue"
import { Button } from "@mar7th/march7th-ui-vue/components/button"

OKLCH 动态主题

组件库使用 @mar7th/march7th-theme 提供的 OKLCH 动态色相主题。--m7-hue 控制整套品牌色，默认值为 215；同时保留 shadcn-vue 的 background、primary、accent 等语义变量，因此官方组件不需要修改源码即可使用新配色。

建议在应用挂载前初始化主题，避免页面首次渲染时出现明暗模式闪烁：

import { createApp } from "vue"
import { initializeMarch7thTheme } from "@mar7th/march7th-ui-vue/components/theme"
import "@mar7th/march7th-ui-vue/style.css"
import App from "./App.vue"

initializeMarch7thTheme()
createApp(App).mount("#app")

主题组件提供浅色、深色、跟随系统和动态色相选择：

<script setup lang="ts">
import { HuePicker, ThemeSwitch } from "@mar7th/march7th-ui-vue/components/theme"
</script>

<template>
  <ThemeSwitch show-labels />
  <HuePicker class="mt-4 max-w-sm" />
</template>

defaultHue 默认是 215，传入的值会被限制在 0 至 360 以及组件 min、max 范围内；点击重置会回到该自定义值。主题模式和色相分别保存在 m7-theme:mode 与 m7-theme:hue，完整说明参见 docs/guide/theming.md。

Toast 通知推荐使用 March7th 包装组件，它默认启用语义状态色并自动跟随当前实际明暗模式：

<script setup lang="ts">
import { toast } from "vue-sonner"
import { ToastHost } from "@mar7th/march7th-ui-vue/components/toast"
</script>

<template>
  <button type="button" @click="toast.success('发布成功')">显示通知</button>
  <ToastHost close-button position="bottom-right" />
</template>

普通、成功、信息、警告和错误通知分别映射到 March7th 主题 Token；npm 包的 style.css 已包含 vue-sonner 基础样式。

本地开发

安装依赖并启动独立组件开发中心：

pnpm install
pnpm dev

开发中心使用 src/preview 中的组件演示、使用代码和 API 数据，修改 src/components/ui 后页面会通过 Vite 热更新直接反映变化。

文档站使用 VitePress，源文件位于 docs：

# 开发文档
pnpm docs

# 构建文档
pnpm docs:build

# 预览已构建的文档
pnpm docs:preview

复制组件源码

仓库内可以使用以下命令复制组件：

# 查看组件
pnpm copy --list

# 复制单个组件及其本地依赖
pnpm copy button --target ../my-vue-app

# 复制全部组件
pnpm copy all --target ../my-vue-app

# 覆盖目标文件并安装 npm 依赖
pnpm copy all --target ../my-vue-app --overwrite --install

发布到 npm 后，也可以不克隆本仓库直接复制：

pnpm dlx @mar7th/march7th-ui-vue button \
  --target ../my-vue-app \
  --install

复制工具会递归复制 Registry 本地依赖。例如复制 Button 时，会同时复制 src/lib/utils.ts。目标项目建议已经配置 Vue 3、Tailwind CSS v4、components.json 以及 TypeScript 路径别名；没有 components.json 时，工具会使用默认的 @/components/ui、@/lib 和 @/composables 目录。

构建与检查

# 类型检查
pnpm typecheck

# 构建 npm 组件库
pnpm build

# 构建本地开发中心
pnpm dev:build

# 生成并构建 Registry
pnpm registry:build

# 构建 VitePress 文档站
pnpm docs:build

# 检查 npm 发布包内容
pnpm pack:check

主要生成目录：

• dist：npm 组件库产物。
• .dev-dist：独立开发中心产物。
• public/r：Registry JSON。
• docs/.vitepress/dist：VitePress 文档站产物。
• docs/components/*.md：根据 src/preview 数据生成的组件文档。

这些目录和文件均由脚本生成并已加入 .gitignore，不需要提交 Git。

同步 shadcn-vue

项目只维护 src/components/ui 这一份最终组件源码，不提交额外的官方源码副本。同步脚本会在 .cache/shadcn-vue-registry 创建隔离项目，通过当前安装的 shadcn-vue CLI 和 new-york-v4 Registry 生成官方组件，应用可选转换后再同步到正式源码目录。

检查 Registry 更新

不修改正式源码，只检查当前 CLI 和官方 Registry 是否产生变化：

pnpm upstream:update:check

检测到以下任一变化时，命令会输出 Official Registry updates are available. 并以退出码 1 结束：

• shadcn-vue CLI 版本变化。
• 官方组件源码或 Registry 元数据变化。
• 同步样式、别名或转换配置变化。
• 本地组件与预期同步结果不一致。

因此，ELIFECYCLE Command failed with exit code 1 在检查到更新时是预期结果，方便 CI 判断存在待同步内容，并不代表组件生成失败。

同步当前版本

使用项目当前锁定的 CLI 版本同步全部组件并执行基础验证：

pnpm upstream:update

同步器会依次执行：

1. 刷新 .cache/shadcn-vue-registry 中的隔离项目。
2. 执行 shadcn-vue add --all --overwrite。
3. 记录自动转换前的官方源码哈希。
4. 执行 scripts/component-transforms.mjs 中启用的转换。
5. 更新 src/components/ui 和 src/index.ts。
6. 更新 Registry 元数据并补充缺失的 npm 依赖。
7. 执行类型检查、组件库构建和 Registry 构建。
8. 验证通过后更新 shadcn-sync.json 中的 CLI 版本、哈希和同步时间。

只同步文件、暂时跳过基础验证时可以使用：

pnpm upstream:update -- --skip-validate

正式升级不建议跳过验证。

升级 shadcn-vue

升级前建议保持工作区干净，并在独立分支中操作：

git status --short
git switch -c chore/update-shadcn-vue

升级当前 package.json 版本范围允许的版本：

pnpm update shadcn-vue

明确升级到 npm 最新版本，包括可能存在的主版本升级：

pnpm up -D shadcn-vue@latest

然后依次执行：

# 预览新 CLI 和 Registry 带来的变化；发现变化时退出码 1 属于正常情况
pnpm upstream:update:check

# 接受新版本并更新组件、Registry、依赖和同步基线
pnpm upstream:update

# 确认同步后已经没有待处理变化
pnpm upstream:update:check

# 验证开发中心、文档站和 npm 发布包
pnpm dev:build
pnpm docs:build
pnpm pack:check

如果 CLI 版本发生变化但组件文件没有变化，第一次检查仍会返回退出码 1，因为同步基线包含 CLI 版本。执行 pnpm upstream:update 接受新基线后，再次检查应以退出码 0 结束。

最后检查实际变更：

git status --short
git diff --stat
git diff -- src/components/ui
git diff -- package.json pnpm-lock.yaml registry.json shadcn-sync.json

通常需要提交 package.json、pnpm-lock.yaml、src/components/ui、src/index.ts、registry.json 和 shadcn-sync.json。如果官方新增或修改了组件，还需要检查 src/preview/catalog.ts、src/preview/examples.ts、组件演示和相关文档是否需要更新。

定制与覆盖规则

同步规则位于 shadcn-sync.json：

• transforms：启用 scripts/component-transforms.mjs 中的自动转换。
• excludeComponents：完全停止覆盖指定组件。
• preserveFiles：只保留指定文件，其余文件继续同步。
• registryDependencies：为指定组件补充额外的 Registry 本地依赖。
• aliases：在写入正式源码前替换上游源码中的路径。

当前没有启用样式转换。Button 和 Input 使用官方版本；自定义 theme 组件通过 excludeComponents 排除在官方同步之外，carousel/useCarousel.ts 因 npm 声明文件构建兼容问题暂时保留。官方修复对应问题后，可以删除该 preserveFiles 配置，并通过完整构建确认是否可以恢复自动覆盖。

更详细的同步说明参见 docs/guide/upstream-sync.md。

发布

发布前至少运行：

pnpm upstream:update:check
pnpm dev:build
pnpm docs:build
pnpm pack:check

首次验证新版本时发布到 next 标签：

pnpm publish:next

验证稳定并更新正式版本号后发布到 latest：

pnpm publish:latest