components-version-badge

/components:version-badge

实现一个版本徽章组件，在工具提示中显示版本号、Git 提交和近期变更日志。

上下文

• 框架配置：!find . -maxdepth 1 \( -name "next.config.*" -o -name "nuxt.config.*" -o -name "svelte.config.*" -o -name "vite.config.*" \)
• 包管理器：!find . -maxdepth 1 \( -name "package.json" -o -name "bun.lockb" -o -name "pnpm-lock.yaml" \)
• 样式：!find . -maxdepth 1 \( -name "tailwind.config.*" -o -name "postcss.config.*" \)
• UI 库：!find . -maxdepth 1 -name "components.json"
• 变更日志：!find . -maxdepth 1 -name \'CHANGELOG.md\'
• 版本：!jq -r '.version // "unknown"' package.json

参数

• --check-only：分析项目并展示将要实现的内容，但不进行更改
• --location <header|footer|custom>：指定组件位置（默认：header）

概述

此命令会在应用中添加版本显示，其中包括：

• 触发元素：v1.43.0 | 004ddd9（版本号 + 缩写提交哈希）
• 工具提示：完整的构建信息（版本、提交、时间戳、分支）+ 近期变更日志条目
• 构建时处理：零运行时开销

技术栈检测

根据上面的上下文检测项目的技术栈：

1. 框架：

   • Next.js：next.config.js、next.config.mjs 或 next.config.ts
   • Nuxt：nuxt.config.ts 或 nuxt.config.js
   • SvelteKit：svelte.config.js
   • Vite + React：vite.config.* + 依赖中包含 React
   • Vite + Vue：vite.config.* + 依赖中包含 Vue
   • Create React App：依赖中包含 react-scripts
   • Plain React：依赖中包含 React，但未使用特定框架

2. 样式：

   • Tailwind CSS：tailwind.config.* 或 CSS 中包含 @tailwind
   • CSS Modules：.module.css 文件
   • styled-components：依赖中包含 styled-components
   • Emotion：依赖中包含 @emotion/*
   • Plain CSS：回退选项

3. UI 库：

   • shadcn/ui：components.json 中包含 shadcn 配置
   • Radix UI：依赖中包含 @radix-ui/*
   • Headless UI：依赖中包含 @headlessui/*
   • 无：使用原生实现

执行

执行此版本徽章实现工作流：

第 1 步：分析项目

读取 package.json 以识别依赖项。检查框架配置文件、样式配置和现有组件模式。

第 2 步：创建变更日志解析脚本

创建一个用于解析 CHANGELOG.md 的构建时脚本：

位置：scripts/parse-changelog.mjs（或合适的位置）

// Script should:
// 1. Read CHANGELOG.md
// 2. Extract last 2 versions with their changes
// 3. Categorize changes (feat, fix, perf, breaking)
// 4. Output as JSON for NEXT_PUBLIC_CHANGELOG (or equivalent)

变更类型图标：

类型	图标	描述
feat	sparkles	新功能
fix	bug	Bug 修复
perf	zap	性能改进
breaking	warning	重大变更

限制：

• 每个版本最多 3 项功能
• 每个版本最多 2 项其他变更
• 仅包含最近 2 个版本

第 3 步：配置构建流水线

根据框架添加构建时环境变量：

Next.js（next.config.mjs）：

const buildInfo = {
  version: process.env.npm_package_version || 'dev',
  commit: process.env.VERCEL_GIT_COMMIT_SHA || process.env.GITHUB_SHA || 'local',
  branch: process.env.VERCEL_GIT_COMMIT_REF || process.env.GITHUB_REF_NAME || 'local',
  buildTime: new Date().toISOString(),
};

export default {
  env: {
    NEXT_PUBLIC_BUILD_INFO: JSON.stringify(buildInfo),
    // NEXT_PUBLIC_CHANGELOG set by parse-changelog.mjs
  },
};

Vite（vite.config.ts）：

export default defineConfig({
  define: {
    'import.meta.env.VITE_BUILD_INFO': JSON.stringify(buildInfo),
  },
});

第 4 步：创建组件

根据检测到的框架创建相应的版本徽章组件：

组件结构：

src/components/
  version-badge/
    version-badge.tsx     # Main component
    version-badge.css     # Styles (if not using Tailwind)
    index.ts              # Export

要实现的功能：

1. 触发器显示：

   • 从构建信息中获取版本号
   • 缩写提交 SHA（7 个字符）
   • 低调的样式：text-[10px] text-muted-foreground/60
   • 悬停时提亮，以提示可交互
   • 没有构建信息时隐藏（本地开发）

2. 工具提示内容：

   • 使用表格布局的构建信息部分
   • 按类别展示近期变更
   • 确保键盘无障碍访问

3. 无障碍访问：

   • 可聚焦的按钮触发器
   • 带有版本信息的 aria-label
   • 焦点环样式
   • 悬停和聚焦时均触发工具提示
   • 屏幕阅读器友好的内容

步骤 5：集成组件

将组件添加到合适的位置：

常见位置：

• 页眉／导航栏（最常见）
• 页脚
• 设置页面
• 关于弹窗

默认位置：在桌面端和移动端导航栏中，将组件放在页眉主标题下方。

组件变体

React + Tailwind + shadcn/ui

使用 shadcn/ui 的 Tooltip，以及用于合并类名的 cn 工具。

React + Tailwind（无 UI 库）

使用 Radix Tooltip 或自定义 Tooltip 的原生实现。

Vue 3 + Tailwind

使用 Teleport 定位 Tooltip 的 Vue 组件。

Svelte + Tailwind

使用 action 实现 Tooltip 行为的 Svelte 组件。

Plain CSS

生成使用自定义属性进行主题化的 CSS。

构建脚本模板

#!/usr/bin/env node
/**
 * parse-changelog.mjs
 * Parses CHANGELOG.md and outputs JSON for the version badge tooltip
 */

import { readFileSync, existsSync } from 'fs';

const CHANGELOG_PATH = './CHANGELOG.md';
const MAX_VERSIONS = 2;
const MAX_FEATURES_PER_VERSION = 3;
const MAX_OTHER_PER_VERSION = 2;

function parseChangelog() {
  if (!existsSync(CHANGELOG_PATH)) {
    return JSON.stringify([]);
  }

  const content = readFileSync(CHANGELOG_PATH, 'utf-8');
  const versions = [];

  // Parse version headers and their changes
  const versionRegex = /^## \[?(\d+\.\d+\.\d+)\]?/gm;
  const changeRegex = /^\* \*\*(\w+):\*\* (.+)$/gm;

  // ... parsing logic ...

  return JSON.stringify(versions.slice(0, MAX_VERSIONS));
}

// Output for environment variable
console.log(parseChangelog());

标志

标志	描述
--check-only	分析项目并显示将要实现的内容
--location <loc>	指定组件位置（header、footer、custom）

示例

# Implement version badge with auto-detection
/components:version-badge

# Check what would be implemented without changes
/components:version-badge --check-only

# Place in footer instead of header
/components:version-badge --location footer

实现后

实现后：

1. 验证构建：运行构建命令，确保已设置环境变量
2. 测试 Tooltip：检查悬停效果和键盘无障碍访问
3. 更新 CI：确保构建期间可以获取更新日志
4. 编写文档：在 README 中添加版本显示功能的说明

错误处理

• 没有 package.json：发出警告并询问框架
• 未知框架：提供通用实现方案或询问用户
• 没有 CHANGELOG.md：组件仍可在没有更新日志的情况下工作，仅显示构建信息
• 已有组件：覆盖前先询问，并提供合并方案

另请参阅

• version-badge-pattern 技能——详细的模式文档