Appearance
版本与准确性
Version & Accuracy
文档版本、说明准确性和查阅方式
这里回答旧版反馈里的三个问题：是否支持每个版本的文档、注释和说明是否准确、不熟悉组件库时应该怎么查。
结论
| 反馈点 | 当前覆盖情况 | 后续建议 |
|---|---|---|
| 是否能支持每个版本的文档 | 当前文档站展示当前主线文档，不是多版本文档站。安装页已区分正式包和 alpha 包。 | 发版时保留构建产物或按 tag 部署到 /versions/<version>/。 |
| 注释是否准确 | 核心页面已经补了 Props、事件、数据结构和使用限制，但仍需要随源码变更持续校验。 | 改组件、改类型、改服务接口时必须同步更新文档。 |
| 使用介绍是否清楚 | 已有快速开始、按场景接入、选择包、文档地图和本地搜索。 | 新同事优先按场景查，不熟组件名时不要从分类一个个翻。 |
汇报口径
本次改版已经完成版本查询、正式包和 alpha 包区分、版本差异定位、发包后自动触发文档更新、release note 摘要入口和文档使用引导。历史版本完整文档还未落地，已记录为下一阶段待办，需要先确定历史文档产物存储方案。
待办
| 优先级 | 待办项 | 说明 |
|---|---|---|
| P1 | 支持每个历史版本一套完整文档 | 目标路径类似 /versions/3.0.146/，方便旧项目按包版本查看当时的 Props、事件和使用说明。 |
| P1 | 确定历史文档存储方案 | 需要在“提交到仓库”“上传对象存储”“CI 从 Git tag 重建”之间选一种，避免仓库体积或部署复杂度失控。 |
| P2 | 发版时自动生成历史文档入口 | 发版成功后自动把当前文档固化到对应版本目录，并在版本页提供入口。 |
版本文档策略
当前 VitePress 站点是“当前主线文档”：它跟随仓库当前分支构建，适合查看最新维护中的说明。包版本表按使用环境区分：正式包对应线上环境，alpha 包对应测试环境。
如果需要“每个发布版本都有对应文档”，建议按发版 tag 构建并保留静态产物：
| 方案 | 路径示例 | 适用情况 |
|---|---|---|
| 按版本目录部署 | /versions/3.0.132/ | 需要用户在站点里切换历史版本。 |
| 按 Git tag 查看源码文档 | v3.0.132 tag 下的 docs/ | 内部研发排查历史问题。 |
| 只保留最新文档 | / | 只服务当前主项目版本。 |
现阶段如果业务项目锁了旧版本，先用包版本确认源码 tag 或提交，再对照该版本源码里的 Props、类型和导出。当前在线文档默认不承诺覆盖历史版本行为。
私库包版本
查询来源：npm view <package> versions --json --registry=http://verdaccio.atvideo.cc。正式包取最新非预发布版本，alpha 包取最新 -alpha 版本。
| 包 | 正式包（线上） | alpha 包（测试） |
|---|---|---|
@mbjia/components | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/ui | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/hooks | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/services | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/manager | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/upload-manager | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/utils | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/site-env | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/pure-request | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/ve-video-editor | 3.0.146 | 3.0.153-alpha.0 |
@mbjia/ve-canvas-editor | 3.0.146 | 3.0.153-alpha.0 |
@mooliv/cli | 3.0.153 | 3.0.153-alpha.0 |
线上项目不要直接跟随 latest，因为当前私库 latest 可能指向 alpha 版本。线上应显式安装正式包版本；测试环境可以显式安装 alpha 版本。
更详细的最近版本序列和差异范围见 版本差异。
说明准确性边界
文档里的字段、Props、事件和服务说明应以当前仓库源码为准。遇到以下情况时，优先相信源码，并把文档补齐：
| 情况 | 处理方式 |
|---|---|
| 文档字段和 TypeScript 类型不一致 | 以类型定义为准，修正文档字段表。 |
| 文档默认值和组件实现不一致 | 以组件源码 defaultProps、默认参数或解构默认值为准。 |
| 文档事件说明和 eventBus 使用不一致 | 以实际 emit/on 调用为准，补充方向和 payload。 |
| 文档示例跑不通 | 先检查业务前置条件，再修正示例或标注依赖。 |
| 业务组件依赖接口、登录态或 worker | 在组件页写清前置条件，不把它描述成纯 UI 组件。 |
维护者修改组件时，应同步检查 文档维护 里的质量清单。
不熟悉时怎么查
不要先从分类里一个一个打开。建议按下面顺序：
先按任务找
知道自己要做素材管理、上传、AI 搜索、权益、视频处理时，先看 按场景接入。
再用关键词搜
站内搜索支持组件名和功能词。可以搜“素材”“上传”“AI 搜索”“权益”“分页”“弹窗”。
最后查参数
找到组件后，再看对应页面的 Props、事件、数据结构和服务接口。入口汇总在 文档地图。
常见任务入口：
| 你要做什么 | 先看 |
|---|---|
| 页面里用按钮、弹窗、输入框 | 基础 UI |
| 接素材库或素材选择弹窗 | 素材管理弹窗 |
| 接全局上传 | 全局上传 |
| 接 AI 搜索 | AI 搜索 |
| 接会员、点数、权益拦截 | 支付与权益 |
| 不确定该装哪个包 | 选择合适的包 |