企业官网建设流程全解析

• 前端
• 音视频
• 插件系统

本文以 Clappr 开源仓库根目录的CLAUDE.md工程指南为核心骨架，结合仓库内的真实配置文件（babel.base.json、vite.config.base.mjs、vitest.config.base.mjs、.browserslistrc、knip.json等）与源码结构，系统讲解这个插件化 HTML5 媒体播放器 monorepo 的目录组织、共享构建配置、开发/测试/发布命令、代码地图以及安全与工程规范。读完本文，你将能够在 Clappr 仓库中快速定位组件代码、理解其 ES5 发行契约的由来，并正确使用lerna、yarn workspace、Vitest、Knip 等工具链参与开发。

一、项目总体定位

Clappr 是一个开源的、以插件为导向（plugin-oriented）的 HTML5 网页媒体播放器。仓库采用Lerna + Yarn workspaces 管理的 monorepo结构，这是贯穿整个工程的最高约束；与此同时，性能（流媒体播放、DOM 操作、打包体积）是另一个贯穿始终的关注点，所有工程决策都在这两条主线下展开。

值得注意的一点是：CLAUDE.md本身是仓库中一份指南文件的符号链接，其内容面向在仓库中工作的工程师与 AI Agent 协作场景，因此它既是"给 Agent 看的操作手册"，也是真实反映仓库工程形态的一手资料。

二、Monorepo 目录结构

仓库根目录下分为apps/与packages/两大区域，每个包都有独立的package.json，由 Lerna 统一编排（版本策略为independent，见 lerna.json）：

• apps/
  • apps/clappr.io/— 基于 Docusaurus 的官方文档站，权威文档位于其docs/目录下
• packages/
  • packages/player/— 主播放器打包产物（npm 包名@clappr/player），是面向用户的公开入口
  • packages/clappr-core/— 核心架构（@clappr/core）：Player、Core、Container、Playback 等基础组件
  • packages/clappr-plugins/— 官方插件集（@clappr/plugins）
  • packages/clappr-zepto/— 供 Clappr UI 使用的轻量 DOM 工具库
  • packages/hlsjs-playback/— 基于 hls.js 的 HLS 播放实现（@clappr/hlsjs-playback）
  • packages/dash-shaka-playback/— 基于 Shaka Player 的 MPEG-DASH 播放实现
  • packages/html5-tvs-playback/— 面向 HbbTV 智能电视的 HTML5 播放实现（@clappr/clappr-html5-tvs-playback）
  • packages/clappr-telemetry/— 遥测辅助工具
• test/— 共享的 dist 产物冒烟测试辅助（例如针对 issue #2540 的 ES5 子类化契约检查）

从仓库实际内容看，packages/下还存在packages/level-selector/（清晰度切换插件）等额外包，它们在 knip.json 的 workspaces 配置中均有对应条目，说明这份工程指南列出的目录是核心骨架而非穷举。根 package.json 的workspaces字段将apps/*与packages/*全部纳入工作区，并声明engines.node >= 24。

包之间的依赖关系

@clappr/player是最上层聚合包，其 packages/player/package.json 的 devDependencies 同时依赖@clappr/core、@clappr/plugins与@clappr/hlsjs-playback，并通过nx.targets声明了build/release对上游包的依赖顺序。而vite.config.base.mjs中的clapprSiblingSourceAlias()函数，将@clappr/core、@clappr/zepto、@clappr/plugins、@clappr/hlsjs-playback直接别名解析到各包源码入口（src/main.js、src/zepto.js等），保证开发与测试时直接消费源码、构建时再按依赖顺序产出。

三、依赖管理与共享配置策略

依赖放置规则

工程有一条明确的依赖规则：被 2 个及以上包使用的依赖，放在根目录devDependencies；仅单个包使用的依赖，留在所属包的package.json中。包本身不期望被单独安装运行，monorepo 是唯一入口。当引入新的共享工具时，优先放到根目录并删除各包内的重复副本，而不是使用 Yarnresolutions。

共享配置文件一览

Babel 与 ES5 构建管线

babel.base.json 只有一行实质配置：["@babel/preset-env", { "modules": false }]。结合 vite.config.base.mjs 中的babelEs5Output插件可以看到完整链路：Vite 先用 esbuild/rolldown 完成打包与 tree-shaking，随后在generateBundle阶段（SPEC_DEVIATION注释明确说明：这是 Rolldown 重印对象简写后仍能看到最终代码的最后一个钩子）对每个 chunk 调用babelCore.transformAsync，依据babel.base.json与sourceMaps: true完成 ES5 降级并回写 source map。

该工厂还内置了若干定制插件：clapprAssetStrings将.html/.svg以?raw、.scss以?inline内联为字符串资产；umdAmdDefine将 Vite UMD 输出的define([])改写为define(factory)，以满足 AMD 冒烟测试的契约；clapprPlugins在ANALYZE_BUNDLE环境变量存在时注入rollup-plugin-visualizer，产物为dist/bundle-stats.html（含 gzip 体积）。这与工程指南中"每个bundle-check/ANALYZE_BUNDLE=true都使用 rollup-plugin-visualizer"的说明完全对应。

Browserslist 与 ES5 底线（#2540）

.browserslistrc 的注释本身就是一份设计文档，解释了 ES5 底线的由来：

• 仓库的 ES5 下限不只针对html5-tvs-playback，而是全局约束：发布出去的dist/会被 ES5 时代的第三方插件以class继承方式二次子类化；
• 绝不能添加not dead——因为那会剔除 BlackBerry 7/10 与 ie_mob 10/11，而这正是仅存的、能让preset-env保留对class降级的目标集；
• not ie <= 11仍保留 ie_mob 10/11 在目标集中，它们与 bb 7/10 一起构成"无 class 支持"的底线；
• 底线隐含在 caniuse-lite 的份额数据中，由 test/dist-contract.js 中的冒烟守卫在yarn build:dist之后捕捉漂移。

Vitest 共享测试配置

vitest.config.base.mjs 导出defineClapprVitest工厂：默认使用jsdom环境、开启globals、覆盖率 provider 为 v8，并排除**/dist.smoke.test.js（除非是冒烟运行模式）；同时复用clapprSiblingSourceAlias与clapprAssetStrings，保证测试解析到源码别名。它还会在检测到命令行参数包含dist.smoke.test时自动切换为冒烟运行模式（test.include = [SMOKE_GLOB]）。

ESLint 与 Knip

根 eslint.config.js 采用 flat config 形态：忽略dist/、public/、node_modules/、coverage/、*.min.js以及三份不参与 lint 的源码文件（packages/clappr-core/src/base/polyfills.js、packages/clappr-zepto/src/zepto.js、packages/clappr-core/src/base/template.js）；在@eslint/jsrecommended 之上叠加了数量可观的风格规则，例如强制indent: 2、单引号、无分号、no-var/prefer-const、brace-style: 1tbs等，整体风格贴近 StandardJS 的审美。根yarn lint实际执行lerna run lint && eslint test/，因此各包根目录的*.js配置也会被覆盖检查。

knip.json 是面向全部工作区的单一配置，针对根目录与每个包分别定义了entry、project、paths与vitest/babel配置指向；例如根目录 entry 包含test/dist-contract.js与两个共享 mjs 配置，@clappr/player的 entry 包含src/main.js、src/base_bundle.js及三个配置文件。注意文档提示：Knip 只能从仓库根目录运行（yarn knip），否则提升的依赖无法解析；且特定工作区的 key 会替换（而非合并）packages/*全局 glob，因此在覆写时需要重复共享 key。

四、工具链：包管理、开发、构建与测试

包管理器命令

根 package.json 的 scripts 与之对应：dev实为lerna run start --scope=@clappr/player；release为lerna version --include-merged-tags --no-push --yes。而 lerna.json 进一步约束了版本命令：version命令仅允许在main分支执行（allowBranch: "main"）、ciBehindBehavior: "error"、使用conventionalCommits生成版本号与提交信息chore: publish。

本地开发

• 播放器开发：yarn dev→ 启动@clappr/player（默认 http://localhost:8080）
• 核心包：lerna run start --scope=@clappr/core
• 插件包：lerna run start --scope=@clappr/plugins
• 文档站：yarn workspace clappr-docs start

vite.config.base.mjs的serveConfig默认host: 'localhost'、port: 8080，并通过fs.allow: [REPO_ROOT]允许开发服务器访问仓库根目录。

构建、Lint 与测试

单包/单文件测试的几种方式：

• 单包：lerna run test --scope=@clappr/plugins（或@clappr/hlsjs-playback、dash-shaka-playback等）
• 单文件：lerna run test --scope=@clappr/core -- path/to/test.test.js
• 从包根目录直接：vitest run src/path/to/test.test.js，支持--testNamePattern、--watch、--coverage等 Vitest 参数

以@clappr/player为例，其release脚本依次执行四次 Vite 构建（普通 + plainhtml5 变体、各配一个--mode minify），而bundle-check即ANALYZE_BUNDLE=true vite build。冒烟测试契约方面，test/dist-contract.js 用acorn+acorn-walk解析 dist 产物，检测class、箭头函数、const/let、模板字符串、解构简写等 ES5+ 语法残留，一旦yarn build:dist后产物出现这些形式就会失败——这正是 ES5 底线的自动化守卫。

五、文档体系与代码地图（按需加载）

工程指南建议按需打开文档，而不是默认全部读取：

核心代码地图

• Player：packages/clappr-core/src/components/player/（见 player.js 及其测试）
• Core：packages/clappr-core/src/components/core/
• Container：packages/clappr-core/src/components/container/
• Playback 基类：packages/clappr-core/src/base/playback/（见 playback.js）
• Media Control：packages/clappr-plugins/src/plugins/media_control/

插件类型体系包括：CorePlugin、UICorePlugin、ContainerPlugin、UIContainerPlugin、Playback、MediaControl，各自的基类定义在packages/clappr-core/src/base/下（core_plugin/、ui_core_plugin/、container_plugin/、ui_container_plugin/、playback/），并配有一一对应的测试文件。理解这套类型是阅读 Clappr 架构文档和开发插件的起点。

六、判断边界：安全与协作红线

工程指南为 Agent 与开发者划定了明确的三类行为边界：

NEVER（绝对禁止）

• 提交密钥、令牌或.env文件
• 使用eval()或Function构造函数
• 将令牌存入localStorage（优先 httpOnly cookie 或内存）
• 使用innerHTML拼接不可信的用户输入
• 在 console、错误或 URL 中记录或暴露敏感数据

ASK（动手前先询问）

• 新增依赖之前（评估包体积、维护成本与替代方案）
• 对共享包（@clappr/core、@clappr/plugins、@clappr/player）做大规模或高风险改动之前

ALWAYS（始终遵守）

• 使用 Conventional Commits 规范：<type>(<scope>): <description>（描述用英文）
• 优先async/await而非.then()；并行任务用Promise.all()
• 及时清理：定时器、事件监听器、观察者、连接、媒体元素、Blob URL
• 在契合代码库的地方优先组合（composition）而非继承
• 测试行为而非实现；测试彼此独立，用afterEach/afterAll清理
• 暂存与提交前，阅读并执行.agents/skills/commit/SKILL.md（分支检查、Conventional 格式、英文信息）

七、Code Review 与 Skill 机制

• PR 评审：对于 PR 评审、代码评审或任何结构化合入前反馈，需阅读并执行.agents/skills/code-review/SKILL.md——它定义了严重级别（severities）与输出模板。该 Skill 将评审拆分为五个维度：正确性、可读性与简洁性、架构、安全、性能，并要求在对话中交付结论，默认不自动发布到 GitHub。
• 提交 Skill：.agents/skills/commit/SKILL.md覆盖暂存与提交流程。
• 使用原则：任务匹配某个 Skill 时，直接读取其SKILL.md并执行步骤，而不是通过工具间接调用；在回答或执行 git 操作（包括"快速"PR 评审）之前先做这一步；若多个 Skill 同时适用，按合理顺序执行（例如 code-review 先于 commit）。

八、代码风格与工程约定

命名

• 布尔值用is*/has*/can*前缀；方法用动词；类用名词；私有成员用_前缀；常量用UPPER_SNAKE_CASE。

架构

• 播放器组件优先使用类；单一职责；方法控制在约 30 行以内；提前返回（early returns）；倾向组合优于继承。

导入

• 使用 ES6 import；包内优先相对路径。

DOM 与性能

• 批量读写 DOM；缓存引用；事件委托；对 resize 做 debounce/throttle；触摸/滚动监听使用 passive；使用requestAnimationFrame；动画优先transform/opacity。

安全

• 按上下文（HTML、JS、URL）对用户内容做消毒；合并不可信对象时校验键；状态变更请求加 CSRF；校验postMessage的origin；使用具体的targetOrigin（绝不使用"*"）；重定向前校验 URL。

TypeScript（如使用）

• 避免any，改用unknown；接口（interface）描述形状；使用类型守卫；类型声明尽量贴近使用处。

注释

• 注释解释"为什么"，而不是"是什么"。

这些约定在仓库代码中有大量实例：例如 eslint.config.js 强制no-var、prefer-const、单引号与无分号，从工具层面保证命名与格式的一致；而vite.config.base.mjs中SPEC_DEVIATION注释正是"解释 why"的范例。

九、快速上手指引

如果你是第一次接触 Clappr 仓库，推荐的动手路径：

1. yarn install安装依赖（要求 Node >= 24）；
2. yarn dev在 http://localhost:8080 启动播放器开发环境；
3. 阅读 apps/clappr.io/docs/architecture.md 与 apps/clappr.io/docs/getting_started.md 建立整体认知；
4. 按代码地图深入packages/clappr-core/src/components/player/player.js等核心实现，配合同名.test.js理解行为契约；
5. 提交改动前运行yarn lint、yarn test，并遵循 Conventional Commits 与.agents/skills/commit/SKILL.md的流程；
6. 若改动涉及发布产物，在yarn build:dist之后运行yarn test:smoke，验证 ES5 契约未被破坏（对应test/dist-contract.js的守卫逻辑）。

理解这套 monorepo 工程形态，是深入 Clappr 插件开发、构建定制与源码贡献的基础——它决定了依赖放哪里、构建如何降级、测试如何组织，以及每一行代码应当遵循怎样的规范。

• 前端
• 音视频
• 插件系统