ray-template/docs/toolchain-upgrade.md
2026-11-04 15:02:26 +08:00

27 KiB
Raw Blame History

工具链升级记录(2026-11-02)

版本基线

版本通过 npm 官方注册表的 latest 标签核实,锁文件包含对应的完整解析结果。只使用稳定版,不引入 beta/RC。Node.js 使用当前 LTS 26.13.0,pnpm 固定为 12.16.1;本机验证使用校验 SHA-256 后下载到临时目录的 Node,未替换全局 Node。

核心依赖 升级前 当前
Node.js(.nvmrc) 22.12.0 26.13.0 LTS
pnpm 未固定,CI 使用 9 12.16.1
Vite 7.2.6 8.3.5
Vue 3.5.25 3.5.44
Vue Router 4.6.3 5.4.0
Pinia 3.0.3 4.1.0
Naive UI 2.43.2 2.45.3
VueUse 13.1.0 15.0.0
ECharts 6.0.0 6.1.0
Axios 1.10.0 1.21.0
TypeScript 5.9.3 6.0.3(兼容上限)
vue-tsc 2.2.8 3.3.14
Vitest / UI 4.0.12 5.0.5
ESLint 9.39.1 10.14.0
typescript-eslint 8.47.0(拆包) 8.72.1
Prettier 3.6.2 3.9.10
Husky 8.0.3 9.1.7
lint-staged 15.4.3 17.6.0
Mock 数据生成 Mock.js 1.1.0 Faker 10.6.0,中文 locale
SVG 雪碧图 vite-plugin-svg-icons 2.0.1 @spiriit/vite-plugin-svg-spritemap 7.2.0

其余保留的直接依赖也更新为核实到的稳定版并使用精确版本,完整列表见 package.json。没有新版本的依赖保留其已有最新版本。

必要适配

  • 可选 CDN 改为 jsDelivr 的 npm 精确版本路径,使用发布包中实际存在的生产文件;移除已经不在依赖中的 dom-to-image 条目。默认仍使用本地 bundle。
  • Vite 8 使用 Rolldown/Oxc:移除无效 build.transpile,使用 rolldownOptions 和 Oxc 压缩参数,交由原生依赖图拆包;保留路由懒加载、压缩文件、部署 base 与各模式输出目录。
  • Node 配置使用 ESM 路径解析、显式 .ts 扩展名和 JSON import attributes,为 native config loader 做好适配。别名 @api 统一指向实际的 src/api,修正 TS @images/* 映射。
  • 替换旧 SVG 插件的缺失依赖和旧依赖树。RIcon 仍按 prefix + name 访问图标,新插件生成独立带 hash 的雪碧图并跟随部署 base;<use> 使用标准 href。
  • 移除会在开发/构建时自动修改源码的 vite-plugin-eslint;ESLint 10 使用原生 flat config。保留有价值的既有规则,格式交给 Prettier,lint/check 默认只读。
  • 更新 Husky 9 hook,移除 Husky 8 的初始化与旧 package.json hooks。暂存检查使用 --no-warn-ignored,只抑制显式传入已排除声明文件时的提示,真实 lint warning 仍会失败。移除实际未使用的 Webpack sprite loader、depcheck 和重复 ESLint 预设。
  • VueUse 的 MaybeRef/MaybeRefOrGetter 改从 Vue 导入;Axios 仅在已安装解包响应拦截器的边界公开返回 data 的原有接口,补充适配器回归用例。
  • 修复 TSX 演示中对解构 const 使用 v-model 产生的非法赋值,改为绑定组件实例属性。
  • Router 5 的权限守卫改为返回路由结果,保留未登录、角色与白名单判断;首页本身无权限时取消导航以免重定向循环,增加真实内存路由测试。
  • 开发依赖扫描限定 index.html,避免误扫旧构建目录;SVG 预览页的 glob 移到独立 .ts 模块,绕过 Vite 8 扫描器将保留 JSX 当作 JS 的限制。待上游支持后可重新评估该拆分。
  • Vitest 测试只复用 Vue/TSX 与自动导入转换,不启动 Mock 服务、HTML 注入、图标扫描或压缩插件。修复遗漏 await 的断言,更新水印/全屏用例中的过期预期,保留行为断言。
  • 既有颜色转换回归暴露 rgba 空格不一致与八位 hex 透明度丢失,已修正;图表异常保留原始 cause。
  • Mock.js 存在未修复的原型污染公告,且包含直接 eval;替换为 Faker 的中文实例,保持人员字段、分页接口和表格示例能力。新版 Mock 插件的 include 相对 dir 匹配,修正原先重复的 mock/ 前缀并等待首次加载,实际验证了 API 响应。
  • 开发时打开 #/tables/remote,在 Network 的 Fetch/XHR 分类查看 GET /api/list?page=1&pageSize=10。接口使用站点根路径 /api/list,不带 /ray-template/。Vite 按启动日志中的实际端口访问;静态构建的页面使用同一套本地示例生成逻辑,不依赖 Mock 服务器。
  • 浏览器构建和 Autoprefixer 统一到 Vite 8 Baseline Widely Available。开发服务默认 loopback,局域网访问需显式 --host。监听排除全部构建目录和 .ai-local,避免构建报告时触发页面重复重载。
  • CI 与 Docker 使用同一 Node/pnpm,冻结锁文件安装。CI 合并重复流程并覆盖类型、lint、格式、测试、构建;保留检查通过后部署 main 到 dist 分支的行为。

兼容性限制与复查条件

TypeScript 7

npm 最新为 7.0.2,但 vue-tsc 的编译器包装机制尚未完整支持原生 TypeScript 7,typescript-eslint@8.72.1 的 peer 范围也明确为 <6.1.0。因此采用 6.0.3,而不关闭类型检查或制造 peer 冲突。待这两个上游均明确支持后,再解除 Dependabot 对 TypeScript 7 的限制并运行完整验证。

兼容的间接依赖覆盖

pnpm-workspace.yaml 中有三个有限范围的覆盖,避免升级后的上游依赖继续锁定有已知公告的旧大版本:

覆盖 已核实的调用契约 移除条件
@logicflow/core>uuid → 14.0.3 LogicFlow 只使用无参数 v4() 生成 ID LogicFlow 自身升级到已修复版本,且流程图验证通过
minimatch@>=10 <11.0.1 → 11.0.4 ESLint 的匹配函数与类接口仍可用,完整 lint 验证 上游依赖允许 11+,移除覆盖后审计与 lint 通过
glob@>=9 <14.0.2 → 14.0.3 js-beautify CLI 使用 hasMagic、globSync 上游依赖允许已修复版本,移除覆盖后验证通过

依赖构建脚本采用 pnpm allowBuilds 列表。LogicFlow 的 AI 提示 postinstall 不参与运行时构建,明确禁用;其余仅保留已有原生依赖所需脚本。pnpm 自动记录的 minimumReleaseAgeExclude 是本次明确更新到最新稳定版产生的精确版本例外,不是关闭所有供应链检查。

CryptoJS

CryptoJS 4.2.0 已停止维护,但仍是最后一个发布版本。现有同步 AES 接口和密文格式继续保留;只有在同时设计旧密文迁移、异步接口与调用方适配时,才可替换为 Web Crypto。客户端内置密钥不能视为服务端保密边界。

验证记录

在 macOS 本机使用 Node.js 26.13.0 / pnpm 12.16.1 验证:

检查 结果
pnpm env:check 通过;避免与 pnpm 自带 doctor 子命令冲突
冻结锁文件安装、pnpm peers check 通过,无 peer 冲突
全新临时目录 CI=true HUSKY=0 pnpm install --frozen-lockfile --offline 通过,从缓存重建依赖,无需原有 node_modules
pnpm check 类型、ESLint(零 warning)、Prettier、42 个测试文件 / 146 条测试、生产构建通过
pnpm dev-build 通过,输出 dist/development 与 sourcemap
pnpm report 通过,静态报告为 dist/report/stats.html,不打开浏览器或保持报告服务器
vite build --configLoader native 通过,配置不依赖旧加载器的扩展名猜测
可选 CDN 构建 通过;实际引用的 9 个精确版本脚本 URL 全部 HTTP 200,Chrome 登录、首页与 SVG 预览无控制台 error
pnpm audit 0 info / low / moderate / high / critical;无忽略公告配置
pnpm outdated 仅报告 TypeScript 7 的兼容例外与最后版本 CryptoJS 的弃用标记
三个间接依赖覆盖的 API uuid.v4/validate、globSync/hasMagic、minimatch/Minimatch 调用通过
commitlint 合规消息通过,错误格式消息被拒绝
Mock HTTP API /api/list?page=2&pageSize=10 返回 10 条 / total 100;无分页返回 100 条,字段与年龄范围通过
Chrome 开发页面 演示登录、首页、SVG 菜单图标、ECharts 图表、LogicFlow 节点和二维码渲染通过
Chrome 生产预览 登录、首页显示真实依赖版本、高级表格中文数据、10→20 条切换、中英文菜单和明暗主题通过,检查时控制台无 error

截图等本机证据位于忽略目录 .ai-local/evidence/。production-home.png 为生产首页,production-table-dark.png 为英文菜单和深色表格,cdn-svg-icons.png 为 CDN 构建的图标预览。临时安装、CDN 验证配置和产物不进入提交。

CI 工作流仅完成配置和官方 Action 输入核对,尚未在远端执行。当前机器未安装 Docker,因此 Dockerfile 未做实际镜像构建;也未验证真实后端、无界宿主、其他浏览器、最低版本设备和完整打印/下载链路。

生产构建仍提示一个约 2 MB 的公共 chunk(包含模板公共组件依赖)及 ContentWrapper 同时静态/动态导入;功能检查通过,未提高告警阈值来隐藏问题。后续若做性能专项,应基于静态报告拆解组件导出与加载边界,并重新验证路由缓存及初始化顺序。

2026-11-03:Hooks、布局和图标改造验证

未升级依赖或改动锁文件。新增 icons:generate / icons:check,生成脚本使用项目现有 Prettier 配置输出代码,并保留 ESLint 所需的声明空行。Vite 按顶层分包生成独立雪碧图,名称与类型来自同一目录清单。

检查 实际结果
Node.js 26.13.0、pnpm 12.16.1、冻结锁文件安装、pnpm env:check 通过;本机原有 Node 26.12.1 低于项目要求,本轮使用临时 26.13.0 运行时
pnpm typecheck(包含 icons:check)、pnpm lint 通过,未降低规则或增加全局忽略
pnpm format:check / pnpm check 格式检查报本地 TODO.md 与 .vscode/settings.json,保留这两项非本任务变更;pnpm check 在格式阶段停止,未声称全绿
本任务修改与新增文件的 Prettier 检查 通过;生成清单也由项目 Prettier 配置直接格式化
pnpm test:run 单独继续执行,50 个测试文件 / 173 条测试全部通过
pnpm exec vite build 单独继续执行并通过;44 个图标输出为 7 个带 hash 的独立包,各包 symbol ID 无重复
Chrome 开发版 侧边、顶部、混合导航;嵌套页面菜单匹配;定宽 1200px 居中;390px 抽屉打开、选中自动收起且无页面横向溢出;刷新后保留桌面偏好;PNG 截图与元素全屏/恢复
Chrome 生产预览 演示登录、44 个图标渲染、7 个带 base 的图标资源路径、完整图标复制操作、深色主题、中英文新页面文本、内容最大化及 Esc、页面卸载后刷新恢复、内容滚动到 300px、滚动页脚与既有自适应表格渲染

Pinia 设置沿用原持久化 key,旧裸 Logo 名称在读取时迁移;锁屏仍使用历史布尔值格式。对应迁移、并发刷新、滚动实例替换、导航越界、右键异步关闭、全屏帧清理及截图失败处理均有回归用例。

本机截图位于 .ai-local/evidence/2026-11-03/。文件监听首次触发 EMFILE,本轮开发服务使用 CHOKIDAR_USEPOLLING=1 进行验收,未将该环境绕行写入默认开发配置。保留公共 chunk 大小、ContentWrapper 静态/动态导入及 Mock CORS 序列化提示;未调整告警阈值。本轮未验证实际纸张打印、最低版本浏览器或无界宿主。

2026-11-03:自动同步、注释规范与视觉整理

本轮未升级依赖、未改动锁文件。图标生成已接入 dev、build、dev-build、report、check 与 Vite 构建入口;独立 typecheck 和 icons:check 保持只读。AGENTS.md 引入 统一注释规范,页面排版与主题入口见 视觉约定。

检查 实际结果
冻结锁文件安装与 pnpm env:check 通过,使用 Node.js 26.13.0 / pnpm 12.16.1
pnpm check 图标同步、类型和 ESLint 通过;格式阶段仅报未改动的 .vscode/settings.json,未声称全量检查通过
pnpm test:run 单独执行,52 个测试文件 / 181 条测试全部通过
pnpm build 通过,包含自动生成、类型检查和生产构建;最终为 44 个图标、7 个独立雪碧图
无开发服务参与的构建 临时新增 SVG 后先确认 icons:check 报清单过期,再直接执行 pnpm build,自动生成成功;删除临时 SVG 后再次构建恢复最终产物
实际图标 HMR 新增、改名、删除自动同步清单;修改内容后资源 hash 改变且保留搜索状态;新增/删除整个分包自动重建插件配置并通知浏览器重载;带连字符的分包名与符号链接路径的 CLI 执行有回归覆盖
注释位置 移除组件介绍块和重复堆叠;类型、Store 与常量说明按相邻声明重新核对,修正原登录状态说明中错误的存储介质描述
Chrome 排版 工作台、Hooks、布局实验室、图标库;1440/1280px 桌面与 390px 单列,无页面横向溢出;保留登录页紧凑资源入口
主题与语言 生产页明暗切换、暗色选中态前景、中英文标题;修复热更新后国际化实例被替换导致显示原始键的边界,并覆盖初始化前创建 Hook 后恢复翻译的场景

开发验收仍使用本机 CHOKIDAR_USEPOLLING=1,未改动默认监听方式。浏览器控制连接在还原视口时中断,后续通过 Chrome 开发者工具的独立上下文核对最终生产产物;最终截图与阶段记录放在 .ai-local/evidence/2026-11-03/polish/。复杂基础组件自身的 Vue JSX 热替换场景未穷尽,生产验收基于最终完整加载的产物;没有把这些检查写成真实后端、最低版本设备或实体打印验收。

公共 chunk 大小、ContentWrapper 静态/动态导入与 Mock CORS 序列化提示仍保留,未降低检查严格度或调高告警门槛。

2026-11-03 TypeScript 项目配置拆分

旧配置只在 vue-tsc 命令行传入 --noEmit。直接读取项目配置时,allowImportingTsExtensions 会触发 TS5096。现在共享配置声明 noEmit,由根项目分别引用应用、Node 与测试配置。Vue JSX 和自动导入声明由应用及测试配置加载。TypeScript 6 的 DOM 已包含可迭代声明,Vite 继续通过 build.sourcemap 控制开发和生产的 sourcemap。

依赖与锁文件沿用当前版本。完整命令和项目归属见 TypeScript 项目配置。

在 Node.js 26.13.0 与 pnpm 12.16.1 下,pnpm check 通过类型、ESLint、Prettier、59 个测试文件的 240 个用例和生产构建。pnpm dev-build 通过,并生成开发版 JS sourcemap。通过 TypeScript 服务核对了应用入口、Vite 配置、Mock 文件和测试文件各自使用的项目。

2026-11-03 AI Harness 迁移

任务入口、范围清单和验收命令集中在 AI Harness。GitHub Actions 通过 pnpm check 校验上下文与回归路径。旧工具配置和旧开发指南已移除,TypeScript 增量缓存迁至 node_modules/.cache/ray-template/。依赖与锁文件沿用当前版本。

本机 macOS 使用 Node.js 26.13.0 和 pnpm 12.16.1。六个任务域的定向验证均通过。新增回归覆盖空测试目录,以及子命令失败时的退出码、停止执行和 JSON 报告。pnpm harness verify 通过 Harness 校验、类型、ESLint、Prettier、60 个测试文件的 242 个用例和生产构建。

本机报告保存在 .harness-local/runs/,npm pack --dry-run --ignore-scripts 确认本机证据目录不进入发布包。Windows 和 Linux 的执行结果待远端 CI 验证,浏览器验收按 Harness 中的独立步骤执行。

2026-11-03 组件目录与公开演示的检索配置

通用组件统一放在 src/components,保留 @/components 入口并删除没有调用方的 RCollapse。双语 README 补充实际工作台截图、快速开始和二次开发入口。公开构建的 canonical、分享图和 sitemap 按 Vite base 生成,配置方式见部署指南。

  • pnpm harness verify 通过类型、ESLint、Prettier、63 个测试文件的 265 个用例和生产构建。
  • 检查了官方路径、自定义子路径与未设置站点源地址的构建。公开版本的首页、sitemap 和资源 URL 一致;普通构建输出 noindex。
  • Chrome 生产预览验证了桌面双列、390px 单列、中英文与明暗切换、预填演示登录,以及关闭 JavaScript 时的项目介绍和链接。GitHub About 描述、演示地址和主题已回读确认;未部署网站构建或验证搜索引擎收录。

2026-11-04 GitHub Pages 静态发布

线上首页与 dist 分支的 index.html 一致,引用的 js/_toKey-BqfG5Sv9.js 在分支中存在,Pages 却返回 404。发布根目录缺少 .nojekyll,Jekyll 默认过滤下划线开头的文件。Vite 现在将 public/.nojekyll 复制到发布根目录,部署约定见架构地图。

  • 干净的 HEAD 加本次修复复用本机已安装依赖执行 pnpm harness verify,66 个测试文件的 285 个用例与生产构建通过。原工作区的全量检查在 __test__/router/config.spec.ts 初始化时失败,独立执行 pnpm build 通过。
  • 构建产物包含 .nojekyll。生产预览首页引用的 12 个 JS 和 CSS 资源均返回 HTTP 200,内容与产物一致。Chrome 使用演示账号进入首页,控制台无错误。GitHub Pages 待部署后回查。

2026-11-04 文档工作区与页内示例

文档迁入 apps/docs,与后台和 packages/utils 共用根锁文件。VitePress 1.6.4 使用 Vite 6.4.5,覆盖只作用于 VitePress;后台保留 Vite 8.3.5。@/utils/precision 转发共享包,RBarcode 仍由应用维护,文档按需加载原组件。

  • 本机 macOS(Node.js 26.13.0、pnpm 12.16.1)通过 pnpm harness verify,含 66 个测试文件、291 个用例,以及应用和文档生产构建。报告:.harness-local/runs/all-ukYffY/report.json。
  • 检查了 93 个旧路径的目标页和锚点。Chrome 在生产子路径验证了精度输入、条码重绘与非法输入恢复、示例代码、搜索、旧路径跳转、明暗切换和 390px 布局。
  • 当前只验证了本地构建。Docker 镜像、远端 CI 和 GitHub Pages 迁址未验证。

2026-11-04 Ray Admin 与共享能力拆分

Ray Admin 的应用入口迁到 apps/admin,文档和应用经公开入口使用八个共享包。根目录保留开发、构建和 Harness 命令,应用与文档的 Vite 版本分别锁定。pnpm pages:build 生成组合产物,配置站点源地址后另生成旧文档跳转产物。

  • Node.js 26.13.0、pnpm 12.16.1 下冻结锁文件安装及 pnpm harness verify 通过。含包边界检查、独立类型检查、68 个测试文件的 293 个用例,以及后台和文档生产构建。报告位于 .harness-local/runs/all-GPS5No/report.json。
  • 开发服务器的 /api/list 返回 HTTP 200。Chrome 生产预览验证了演示登录、导航偏好刷新恢复、图标和文档交互,覆盖 TablePro 取消及失败重试、外壳导航和主题、精度工具、条码、路由校验、防抖和全屏。检查了 93 个旧路径的目标和锚点,并生成 138 个旧站跳转页。
  • Docker、无界宿主和远端 CI 未运行。旧站迁址需在 GitHub Pages 发布时另行验收。

2026-11-04 文档示例与后台主题联动

文档的组件预览复用后台的 Naive UI 明暗主题和语言配置。页内示例隔离 VitePress 正文样式,依赖后台上下文的示例由 Pages 同一次构建中的 example.html 运行。示例宿主只注册演示路由,使用内存缓存和独立 Store,文档直接引用运行的源码。

pnpm harness verify 通过 69 个测试文件的 294 个用例。合并产物核对了 22 个文档页中的 26 处内嵌入口和源码。Chrome 生产预览验证了 TablePro 样式、明暗主题、中文分页及失败重试,抽测了组件、指令、Hooks、工具交互和正常后台登录入口。桌面和 390px 预览中的边框内边距均为 12px。

参考资料

远端 CI 回查

历史 Ubuntu 失败 的失败项为 detectOperatingSystem.spec.ts。测试读取 Linux 运行器的真实 user agent,断言固定期待 Unknown。提交 83bada95 使用模拟 user agent 和触点数量覆盖各系统。当前基线 80e80775 的 CI 已通过 Ubuntu、macOS、Windows 和部署。现有矩阵继续运行同一条 pnpm check。