版本兼容性与组件体积

1.0 的兼容性边界

当前已发布版本以 npm 和 CHANGELOG 为准。1.0.0 起，公开能力按语义化版本管理：补丁版本修复问题，次版本增加兼容能力，主版本才引入需要迁移的变化。

公开约定包括：

• 文档列出的 props、事件及其参数、插槽参数和 ref 方法。具体清单以 API 文档 为准，不在这里重复维护。
• uni-tree-view 主入口，以及 /shared、/resolver、/global 这三个已公开的子入口。
• key 的类型、受控与非受控模式、单选与多选、禁用节点、固定行高及单位等已说明的行为。

移除公开入口、修改事件参数结构、改变已有参数的含义或默认行为，都需要迁移说明。不能仅为了重构或减小体积而删除现有公开能力。

内部 composable（用于组织 Vue 状态逻辑的组合式函数）、未公开的文件路径和内部 CSS 类名不属于扩展接口。定制节点行应优先使用 node-class、主题参数和插槽，避免绑定内部实现。

Vue 是 peer dependency（由使用组件的项目提供，而不是组件再安装一份的依赖），范围为 Vue >=3.3.0 <4。平台支持和实际验证程度分别见 平台兼容性；版本号进入 1.0 不代表新增了平台或真机验证范围。

保持组件轻量的方式

组件包不包含运行时依赖。主入口只引入树状态、虚拟列表逻辑和自身样式；/shared 的工具函数与 /resolver 的构建工具入口不会因为导入主组件而一并引入。

内置图标使用随组件分发的少量字体数据，不需要安装图标库，也不依赖网络字体。搜索框、弹窗等业务界面由使用方组合，不放进组件本体。

文档站和 playground（本地演示工程）的依赖不等于组件的运行时依赖。它们的完整构建大小不能用来判断引入树组件的成本。

如何测量最终组件产物

仓库提供可重复的生产构建检查：

pnpm install --frozen-lockfile
pnpm check:size

检查使用同一套 uni-app 构建工具，分别构建：

1. 不引入树组件的最小应用，作为对照基线。
2. 只多引入一个树组件的同样应用。

H5、微信和支付宝各比较一次完整输出的差值。因此，组件逻辑即使被编译器放进公共脚本，也会被计入，而不会只统计组件同名的几个文件。临时工程不导入演示页面、wot-ui 或文档站。

结果写入 artifacts/component-size/report.json：

• 原始字节数：构建后脚本、模板、样式及资源的实际大小，小程序主要使用这个指标。
• gzip 字节数：逐文件 gzip 压缩后大小之和，用于估算 H5 压缩传输的增量；它不等于小程序上传包的大小。
• source map（用于把构建代码映射回源文件的调试文件）和开发者工具的项目配置不计入运行产物。

体积预算是阻止意外膨胀的检查上限，不是所有业务项目的固定增量。业务工程已使用的框架能力、编译器版本、分包及开发者工具的二次处理都会影响最终结果。超过预算时，应先检查新增依赖和资源，再决定是否有理由调整 scripts/check-component-size.ts 中的上限。

npm 分发包是另一种指标

pnpm pack:npm

该命令构建并检查 npm tarball（npm 打包生成的压缩包文件，通常为 .tgz），检查内容包括公开入口、类型文件、必要源码以及不应打包进去的文件。

.tgz 中还包含类型声明、README 和变更日志，因此它的压缩大小不等于业务项目实际增加的运行代码。分发包检查与最终组件体积检查各自承担不同职责，不能互相替代。

开发检查与版本发布

日常提交与发布是两条流程。提交前按变更范围选择检查，详见 贡献指南；纯文案勘误不需要完整构建。

需要完整本地校验时，只运行：

pnpm check:all

该命令包含常规代码检查、实际 playground 的微信/支付宝构建、最小工程三端体积检查以及文档与在线示例构建；它不提升版本、不创建 tag，也不发布。无需再逐项重复执行这些检查。

维护者准备发布新版本时，在功能代码已提交并合入干净的 main 后运行 pnpm release，发布流程会自动调用完整校验，通过后才创建版本提交和 tag。确认产物后再执行 pnpm release:push；DCloud 插件市场仍需在 HBuilderX 中手动发布。普通提交不需要运行这两个发布命令，release:prepare 也不应作为日常检查单独运行。