企业官网建设流程全解析

• 音视频
• 前端

本文基于仓库根目录的 CLAUDE.md（AGENTS.md 仓库导航图）展开，结合 package.json、scripts/cli.js、jest.config.js 等真实配置，系统讲解 xgplayer 这个多包（monorepo）仓库的定位方法、常用命令、协作规则与调试路径。读完本文，你将能快速在 16 个功能包中找到目标源码、按规范跑通开发/构建/测试流水线，并理解贡献者必须遵守的红线与质量门禁。

一、仓库定位：这是一份给开发者的“仓库地图”

xgplayer 采用 Yarn Workspaces 管理的 monorepo 结构，根目录的 CLAUDE.md 本质上是一份全局 Agent/开发者导航图（AGENTS.md），它的设计原则是：包级的设计背景与细节应放在各包自己的文档中，根目录只保留"去哪找什么"的索引。因此这份文档没有长篇大论，而是用多张表格把仓库的关键信息压缩成可快速查询的清单——Locate（定位）、Commands（命令）、Rules（规则）、Never（红线）、Debug（调试）。

对第一次接触该仓库的开发者或 AI 编码助手来说，这份地图的价值在于：不需要通读所有源码，就能按图索骥地找到正确的文件、跑出正确的命令、避开常见的破坏性操作。

二、Locate：按需求快速定位源码与工具

从实际目录看，这份表格完全落地：

• 核心播放器位于 packages/xgplayer/src，其中player.js、mediaProxy.js、instManager.js构成播放器主体，plugins/下按功能拆分成 controls、progress、volume、danmu、heatmap、pip 等几十个独立插件；
• 流媒体/转封装扩展包包括 xgplayer-hls、xgplayer-flv、xgplayer-dash、xgplayer-mp4、xgplayer-mp4-new、xgplayer-transmuxer、xgplayer-streaming-shared 等，它们与核心播放器解耦，通过插件方式接入；
• 周边能力包有 xgplayer-ads（广告）、xgplayer-cast（投屏）、xgplayer-music（音乐播放）、xgplayer-subtitles（字幕）等，各自维护独立的package.json与 CHANGELOG；
• 构建工具集中在scripts/下：cli.js是统一的命令行入口，commands/存放 dev/build/link/changelog/release 的具体实现，workflow/存放发布相关的脚本；
• 演示页面按格式分目录组织，例如 fixtures/xgplayer/index.js 就是一个最小 demo，直接用new Player({ id: 'player', url: '...' })拉起播放器。

包级文档与根文档的分工

CLAUDE.md 明确要求"包级的设计/背景信息放在包文档或包级 AGENTS.md 中"。这意味着阅读具体功能时，应优先查阅packages/<pkg>/README.md与CHANGELOG.md——例如 packages/xgplayer/README.md 是配置项大全，packages/xgplayer/CHANGELOG.md 记录了每个稳定版本的变更历史。根目录地图只负责指路，不重复包内细节，避免信息双份维护。

三、Commands：从安装到发布的命令手册

根目录package.json的scripts字段与 CLAUDE.md 的命令表一一对应，可直接照抄运行：

演示命令：按格式选择 fixtures

package.json中为每种媒体格式都预置了演示脚本，全部经由统一的yarn libd dev <dir>转发到scripts/cli.js：

yarn dev:xgplayer # 基础播放器，fixtures/xgplayer yarn dev:hls # HLS 播放，fixtures/hls yarn dev:hlsjs # hls.js 接入，fixtures/hlsjs yarn dev:flv # FLV 播放，fixtures/flv yarn dev:flvjs # flv.js 接入，fixtures/flvjs yarn dev:mp4 # MP4 播放，fixtures/mp4 yarn dev:dash # DASH 播放，fixtures/dash yarn dev:music # 音乐播放，fixtures/music yarn dev:subtitle # 字幕，fixtures/subtitle yarn dev:ads # 广告，fixtures/ads yarn dev:cast # 投屏，fixtures/cast

以 scripts/commands/dev/index.js 的实现为证：该命令本质是拉起一个Vite dev server，默认端口 8081（-p, --port），可用-o, --open自动打开浏览器；它会把传入的dir解析成相对仓库根目录的页面路径，并自动补全index.html。也就是说yarn dev:mp4等价于在 Vite 服务里打开fixtures/mp4/index.html。

构建命令：单包构建与全量构建

scripts/cli.js 定义了build子命令：

yarn build # 等价于 yarn libd build，默认构建 yarn build:all # 等价于 yarn libd build -a，构建全部包 yarn libd build <pkg> # 仅构建指定包

claude.md 调试表里还有一条实用提示："源码修改后 demo 不更新，需要重建对应包的es/输出"，说明构建产物（es/目录）是 demo 直接引用的中间形态。

测试命令：静默模式与 CI 模式

yarn test # jest --verbose，全量详细输出 yarn test --verbose=false --silent # 静默模式，适合例行检查 yarn test:ci # jest --verbose --ci --coverage，CI 用 yarn test:coverage # 覆盖率检查

结合 jest.config.js 可以看到测试体系的真实配置：

• 测试范围（testMatch）：覆盖xgplayer、xgplayer-dash、xgplayer-flv、xgplayer-hls、xgplayer-streaming-shared、xgplayer-subtitles、xgplayer-transmuxer、xgplayer-cast八个包的__tests__/**/*.(spec|test).js；
• 模块映射（moduleNameMapper）：测试中xgplayer、xgplayer-transmuxer、xgplayer-streaming-shared直接指向各自src/，图片与样式资源被__mocks__/fileMock.js、styleMock.js替换；
• 覆盖率统计（collectCoverageFrom）：集中在 dash/flv/hls/transmuxer/cast 的源码上，排除index.umd.js；
• 环境：testEnvironment: 'jsdom'，配合jest.setup.js做全局初始化。

四、Rules：贡献代码必须遵守的协作规则

CLAUDE.md 的 Rules 部分定义了四条硬性约定，直接约束每次提交的质量：

1. 包管理器固定 Yarn 1.x：仓库只用 Yarn 1.x，yarn.lock是唯一允许被锁文件触碰的产物，禁止用 npm/pnpm 等其它工具重新生成锁文件；
2. 依赖锁定审慎：保持依赖版本有意为之，不允许临时放宽或降级依赖；
3. 提交信息规范：使用有意义的 Conventional Commits 标题；跨包改动标注monorepo或*；非平凡改动必须写简短正文，说明问题与关键变更；
4. CHANGELOG 只记稳定版本：仅为 patch/minor/major 稳定发布追加条目，rc/alpha/beta预发布标签的提交要合并进下一个稳定版本的条目中，而不是单独记录。

这些规则与scripts/commands/changelog（yarn libd changelog，支持-s/--single仅生成一份根级 CHANGELOG）配合使用，保证发布历史干净可读。

五、Never：不可触碰的红线

以下操作在仓库中是被明令禁止的，无论出于什么目的：

• 发布/推送/打 tag、修改version、force-push、改写共享历史；
• 提交dist/、es/、node_modules/、日志或系统垃圾文件；
• 添加未经审计的运行时网络请求或远程脚本（安全考量）；
• 切换包管理器或用其它工具重新生成锁文件。

其中"不提交dist/、es/"与构建产物策略呼应——产物只在发布流水线中产生，源码仓库保持干净；"不添加未经审计的网络调用"则与该播放器项目对依赖与安全性的审慎态度一致。

六、Debug：按症状快速定位问题

这条表的实践价值在于：不同症状指向不同的责任层。例如 HLS 播不了，按地图指引应先查共享的xgplayer-hls、xgplayer-transmuxer、xgplayer-streaming-shared，而不是去改核心播放器；fixtures/<format>/目录既是复现现场也是验证入口，配合yarn dev:<format>可以边改边验。

七、质量门禁：quality-gates 里的工程验收标准

导航图指向的 docs/ai-harness/quality-gates.md 进一步细化了工程质量的验收维度，与 CLAUDE.md 的 Rules 互补：

• TypeScript/语法：使用工作区工具链，按包执行构建/类型检查/测试；不要对单个文件运行tsc --noEmit（会忽略包上下文产生误导性报错）；优先async/await；
• 命名与注释：命名体现行为或生命周期边界而非存储/重试机制；注释只写非显然的约束与取舍；
• 架构可维护性：坚持插件优先设计，功能逻辑不进入核心——这正是 xgplayerplugins/目录大量独立插件的设计依据；优先共享模块、工厂与薄适配器，避免重复的变体逻辑；
• Lint/格式化：改动的 JS/TS 文件必须过 Biome（yarn lint即biome check --write packages）；范围要窄，不做无关的历史清理；
• 兼容性/公开 API：不破坏入口、options、事件、配置语义与导出类型；共享 API 变更要同步更新下游包与 demo/文档；
• 测试：优先为受影响行为写聚焦测试；行为跨运行时/协议/选源/回退/生命周期边界时，本地单元测试与集成路径都要覆盖；不弱化断言、不跳过受影响用例；
• 覆盖率：yarn test:coverage或对比coverage/coverage-summary.json，不允许语句/分支/函数/行覆盖率下降，不许通过降低阈值、收缩collectCoverageFrom、弱化testMatch等方式掩盖下降。

结语：把地图用起来

CLAUDE.md 的价值不在篇幅，而在"索引"的精准性。对于开发者，按 Locate 表可以秒级定位任意包的源码与文档；按 Commands 表可以在演示、构建、测试、发布之间无缝切换；Rules 与 Never 定义了提交质量的边界；Debug 表则把常见故障引导到正确的责任层。对于 AI 编码助手，这份文档本身就是一份高质量的系统提示词——它明确了"去哪里、干什么、不干什么、坏了查哪"，是理解并安全协作于该 monorepo 的起点。

• 音视频
• 前端