ArtPlayer/refactor/toolchain-setup.md

# 可重跑的开发环境

用户指定 packageManager 使用 Yarn。标准组合为 Node 24.21.0（根 .node-version）和 Yarn Classic 1.22.22（根 package.json），唯一维护的安装锁文件为 yarn.lock。Yarn 版本沿用仓库原有 v1 锁格式；播放器消费者 API、包版本和浏览器构建目标不受该选择影响。

## 使用

1. 切换到 .node-version 指定的 Node，安装 Yarn 1.22.22；例如 `npm install --global yarn@1.22.22`，然后确认 `node --version` 和 `yarn --version`。npm 仅可用于安装 Yarn 工具及消费者兼容检查，不用于维护本仓库依赖锁。
2. 干净 checkout 执行 `yarn install --frozen-lockfile --non-interactive`，禁止 CI 自动更新锁或忽略安装脚本/engines。参见 [Yarn Classic install](https://classic.yarnpkg.com/en/docs/cli/install/)。
3. 执行 `yarn check:toolchain --strict`，核对实际 Node/Yarn、根固定开发工具和 22 个 workspace 的声明及传递依赖锁条目。工具数量以本次输出为准；普通检查允许满足最低工具要求的 Node，同时打印标准版本。
4. 执行 `yarn test:playback`、`yarn test:dash-control`、`yarn build all` 和 `yarn workspace artplayer-vitepress build`。ENG-02 已拆分只读 lint 与 lint:fix；PR/主线入口和独立 Pages 流程见 ci-setup.md。

私有根包最低 Node 为 ^20.19.0 || >=22.12.0，与原本使用的 Vite 7 一致。标准工具链验证
使用 Node 24.21.0；CI-01 已在 Windows 的 20.19.0/22.12.0/24.21.0 上重装消费相同
core/chapter tarball，见 [Node 记录](changes/2026-09-13-CI-01-node-consumers.md)。
这不是在最低 Node 上完成仓库工具链的干净安装/构建测试，也不是发布包的最低 Node 声明。
CORE-25 默认选项缺陷已修复并通过相同三 Node 与严格打包检查，见
[修复记录](changes/2026-09-13-CORE-25-defaults-ssr.md)；完整工具与消费范围由 CI-01 继续验证。

## 锁文件和依赖维护

- 根构建工具固定精确版本并放在 devDependencies；发布包的 dependencies/peer 范围保持原样。
- SITE-05 将已有传递依赖 `htmlparser2@10.1.0` 显式声明为根 devDependency，供
  `yarn check:site-links` 解析生成 HTML 使用；不进入播放器包。原版本和完整性不变，
  根 yarn.lock 只合并新增的精确选择器。链接检查不执行 HTML 的脚本，不请求外部 URL。
  文档站 FlexSearch peer 已对齐 0.7.43，见[搜索验证](changes/2026-09-16-SITE-05-search.md)。
  Yarn workspace add 后须再从根目录安装并核对 resolutions，防止工作区子命令遗漏根覆盖。
- PKG-JASSUB-09 新增根 devDependency `pngjs@7.0.0`，在 Node 中解码 Playwright 截图，
  用实际合成画面与转移画布 readback 对照；不进入发布包。仅新增其精确 Yarn 锁条目，
  并验证固定 Node/Yarn 的 frozen 安装及严格工具链检查。上游 API 见
  [pngjs 文档](https://github.com/pngjs/pngjs#sync-api)。
- ENG-04 新增 typescript-compat（npm:typescript@4.3.5）作为旧编译器消费探针；源码继续使用 typescript 5.9.3。精确 npm alias 也由锁检查保护；实际覆盖与命令见 [类型检查说明](typechecking.md)。
- 添加根开发依赖使用 `yarn add --dev --exact --ignore-workspace-root-check <name>@<version>`，包级依赖使用 `yarn workspace <name> add ...`；运行依赖升级需要独立兼容证据。
- manifest 和 yarn.lock 同次提交；不提交 package-lock.json、bun.lock 或第二份安装锁。旧 npm 锁及验证报告保留于 ENG-01 Git 历史，原本地 Yarn 锁也已在忽略缓存中备份。
- 新增 @yarnpkg/lockfile 1.1.0 为显式开发依赖，供检查器使用 Yarn 官方锁解析器；不依赖 Lerna 偶然安装的传递依赖。只验证 registry 依赖图及完整性字段，实际下载完整性由 Yarn 安装验证；peer 兼容仍由消费者测试和安装报告验证。
- 另将原已解析的 TypeScript 5.9.3 和 @vue/compiler-sfc 3.5.28 显式声明为根开发依赖，满足 ESLint 工具链 peer 要求，防止依赖偶然提升到根目录；不在本任务迁移生产 TS 或更新公开声明。
- packageManager 字段只是声明，严格检查核对实际执行工具。Yarn 不像 npm lock 一样存储 workspace manifest 副本，workspace 名称/版本的发布基线仍由 refactor 清单和版本任务维护。
- 用户已选 Yarn；MOD-01 可在独立目录评估 Bun，但不能凭试点结果自行替换默认包管理器。
- 现有 npx/npm 脚本入口仍可用，脚本整理由 MOD-02 接续；新增脚本采用本地依赖。当前 postinstall 的 Lerna prepare 在 22 包均无 prepare 时为空操作。

## 验证记录

SITE-03 新增根开发依赖 `monaco-editor@0.30.1`，仅为桌面编辑器提供与既有
Monaco 浏览器资产匹配的精确 API 类型。只使用 type import，不替换 vendor
或加入播放器产物；root yarn.lock 仅增加该版本的一个条目。新增
`yarn test:site-editor` 验证编辑器状态/读取失败；浏览器检查仍使用原 assets/js/vs。

ENG-01 的 [npm 验证报告](baselines/toolchain-validation.json) 是切换前历史证据，不代表 Yarn 已验证。[Yarn 验证报告](baselines/yarn-validation.json) 记录最终干净冻结安装、20 项 Node 测试、21 库包 63 产物及文档站构建全部通过；63 产物 SHA-256 与 ENG-01 完全相同。保留的旧锁条目版本变化为零，9 个 workspace runtime 依赖解析与 npm 基线一致。搜索 peer 后续已由 SITE-05 对齐版本并完成三引擎交互验证；未启用的托管提供方警告保留说明。

构建通过不代表运行时、类型、真实浏览器或 npm 发布验收已完成。Chrome 不可用时按 release-reviews.md 使用内置浏览器并注明实际环境。

## 可选原生浏览器诊断工具

PKG-HLS-SDK-01 将官方 Microsoft ProcDump 12.01 解压到忽略的
`refactor/.cache/toolchains/procdump`，运行时核对精确哈希和 Authenticode。
用途仅为本次HLS测试的Firefox子进程异常取证，配合PowerShell 7.6.5；
不进入npm依赖或CI默认安装，不更改Yarn/锁文件。来源、校验值、许可接受、
权限限制和复现命令见[原生取证记录](changes/2026-09-15-PKG-HLS-SDK-01-native-exception.md)。