企业官网建设流程全解析

Vant 4 完整版本发布记录解析：从 v4.0.0 到 v4.9.0 的演进路线、新组件与升级决策指南

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant

本文基于 Vant 官方仓库中的 changelog.en-US.md 编写，完整覆盖 Vant 4 从 v4.0.0-alpha.1 到 v4.9.0 的全部版本记录（共约 40 个版本条目）。作为移动端 Vue UI 组件库的维护者、贡献者或使用者，通过阅读本文你可以系统掌握 Vant 4 的版本演进节奏、每个版本新增的功能与修复的缺陷、新增组件的引入方式，以及 Vant 官方关于"变更日志迁移"和"语义化版本发布策略"的完整决策。文中所有组件、属性和 API 结论均可在仓库源码（packages/vant/src/各组件目录）中得到验证。

一、重要公告：Changelog 的迁移与历史归档

阅读这份 Changelog 前，首先需要了解 Vant 官方对变更日志本身的重大决策。

从 v4.9.0 起，Vant 的 changelog 将发布在 GitHub Releases Page 上，本页面（packages/vant/docs/markdown/changelog.en-US.md）不再更新。官方给出的理由是"为了避免重复维护、降低成本"（To avoid redundant maintenance and reduce costs）。这意味着：

• 本文档只包含 Vant v4.0.0 ~ v4.9.0 的变更记录；
• 更新版本的变更记录请直接查看 GitHub Releases；
• 更早期版本的记录可参考 Vant 2 与 Vant 3 各自的 changelog。

二、版本发布策略：语义化版本与发布节奏

Vant 遵循 Semantic Versioning 2.0.0（语义化版本规范），其版本号格式为主版本号.次版本号.修订号，各段位的发布节奏如下：

从实际记录看，Vant 4 的 Patch 版本更新确实非常密集——例如 2024 年 1 月至 4 月间连续发布了 v4.8.1 至 v4.8.11 共 11 个修订版本，平均约 1~2 周一个版本，与官方声明一致。同时值得注意的是v4.8.9 被官方明确标记为"Invalid version, please do not use it"（无效版本，请勿使用），这也是仓库中少见的"作废版本"记录，提示我们在生产环境锁定版本时应当避开该版本。

三、新增组件总览：Vant 4 演进中的新成员

从 Changelog 中可以梳理出 Vant 4 生命周期内陆续加入的组件。其中多数在 v4.0.0 正式版发布前（含 RC/Beta/Alpha 阶段）已经引入，此后在 4.x 小版本中仍持续新增组件：

3.1 v4.0.0 系列引入的组件

3.2 4.x 小版本中新增的组件

• v4.1.0 新增 TextEllipsis（文本省略组件），由 [@wjw-gavin] 贡献；
• v4.2.0 新增 Watermark（水印组件），由 [@HuberTRoy] 贡献；
• v4.3.0 新增 Signature（签名组件），由 [@LIjiAngChen8] 贡献；
• v4.4.0 新增 Barrage（弹幕组件），由 [@zhousg] 贡献；
• v4.5.0 新增 FloatingPanel（浮动面板组件），由 [@zhousg] 贡献；
• v4.6.0 新增 FloatingBubble（浮动气泡组件）与RollingText（滚动文本组件），分别由 [@zhousg] 与 [@cunzaizhuyi] 贡献；
• v4.8.0 新增 Highlight（高亮组件），由 [@wjw-gavin] 与 [@inottn] 共同贡献。

这些组件目前在仓库中均有完整实现，例如 Highlight.tsx 及其类型定义 types.ts（导出HighlightThemeVars主题变量类型）、RollingText.tsx、FloatingPanel.tsx、Signature.tsx 等，均可按需查看源码深入了解。

四、重点版本深度解析

4.1 v4.9.0（2024-05-02）：最后一份站内 Changelog

作为站内 changelog 的收尾版本，v4.9.0 引入了三个值得关注的新特性：

1. Calendar 新增switch-mode属性：允许在日历头部通过按钮快速切换"年/月"或"月/日"视图模式。源码中该属性定义于 Calendar.tsx（switchMode: makeStringProp<CalendarSwitchMode>('none')），默认值为'none'表示不可切换，并在 CalendarHeader.tsx 中根据switch-mode === 'year-month'决定是否渲染年份切换操作。仓库同时提供了对应的测试文件 switch-mode.spec.ts 与示例 SwitchModeField.vue。
2. PickerGroup 新增show-toolbar属性：控制是否显示顶部工具栏。源码中该属性为truthProp（默认true），见 PickerGroup.tsx，并在渲染时根据其值条件输出工具栏，见 PickerGroup.tsx。
3. CLI 支持 Rsbuild 配置：构建工具链向 Rsbuild 演进。

此外该版本修复了 Highlight 在keywords为空时的渲染问题、ImagePreview 的swipeItem可能为 undefined 的问题、IndexBar 在同时传入sticky与stickyOffsetTop时锚点渲染不正确的问题，以及 vant-cli 的 Vue SFC 样式绑定失效问题。

4.2 v4.8.0（2023-11-19）：新增 Highlight 组件

v4.8.0 的核心是Highlight 高亮组件的加入（PR #12434）。该组件用于在一段文本中高亮显示指定的关键词，源码位于 Highlight.tsx，配套类型定义 types.ts 提供HighlightThemeVars主题变量类型。同版本还新增：

• ImagePreview 暴露resetScale方法；
• Checker（Checkbox/Radio 基类）默认插槽新增checked与disabled参数；
• Row 的gutter支持纵向间距。

4.3 v4.6.0（2023-06-24）与 v4.5.0（2023-06-11）：两个新组件

• v4.5.0 新增 FloatingPanel（浮动面板）：可上下拖拽的面板容器，同期为其补充了lock-scroll（v4.6.4）、swipe-threshold等后续能力；
• v4.6.0 新增 FloatingBubble（可拖拽的浮动气泡）与RollingText（滚动翻牌式数字文本）。同时 Rate 组件新增clearable属性，Picker 优化了多列同时滑动时的动画效果。

4.4 v4.4.0（2023-05-21）：新增 Barrage 弹幕组件

v4.4.0 加入Barrage（弹幕）组件（PR #11760）。同期重要更新包括：Divider 新增vertical属性；Signature 通过devicePixelRatio提升签名清晰度；Uploader 新增reupload属性；Cascader 支持切换 Tab 时将选中项滚动到可见区域。

4.5 v4.3.0（2023-05-03）：新增 Signature 签名组件

v4.3.0 加入Signature（签名）组件。需要特别留意的是v4.3.1 专门修复了"Vant v4.3.0 安装失败"的问题（#11815），说明 4.3.0 发布包存在问题，使用时应直接升级到 v4.3.1+。

4.6 v4.2.0（2023-04-16）：新增 Watermark 水印组件

v4.2.0 加入Watermark（水印）组件。同期 ShareSheet 支持自定义图标、TextEllipsis 新增dots属性，并修复了 Swipe 在width/height属性变化后未重新调整尺寸的问题。

4.7 v4.1.0（2023-03-05）：新增 TextEllipsis 文本省略组件

v4.1.0 加入TextEllipsis（文本省略）组件。该组件在后续版本中持续演进：v4.2.0 增加dots属性、v4.6.2 增加position属性、v4.8.1 增加toggle实例方法，并在 v4.8.8 修复了组件被 keep-alive 激活时未重新计算省略状态的问题。

五、v4.0.0 大版本的 Breaking Changes 与底层决策

Changelog 记录了 v4.0.0 正式版及其 RC/Beta/Alpha 阶段的关键破坏性变更，这些决策直接塑造了 Vant 4 的形态：

5.1 函数式调用 API 全面重构（v4.0.0-beta.0）

Toast、Dialog、Notify、ImagePreview 四个组件的 function-call API 在 v4.0.0-beta.0 被整体重新设计。如果你正在使用这些组件的函数式调用能力，可以阅读仓库中的实现：例如 function-call.tsx、function-call.tsx、function-call.tsx 与 function-call.tsx。仓库还提供了 vant-compat 兼容包，帮助旧项目平滑迁移。

5.2 Popup 居中样式优化（v4.0.0-beta.1）

Changelog 直接给出了van-popup--center的样式变化对比：

// Vant 3 .van-popup--center { left: 50%; transform: translate3d(-50%, -50%, 0); } // Vant 4 .van-popup--center { left: 0; right: 0; width: fit-content; max-width: calc(100vw - var(--van-padding-md) * 2); margin: 0 auto; transform: translateY(-50%); }

这一改动使居中 Popup 的宽度自适应内容并约束最大宽度，适配更多屏幕场景。

5.3 CSS 变量挂载到 :root（v4.0.0-rc.2）

v4.0.0-rc.2 将 CSS 变量从组件内部挂载位置调整到:root元素上，这是影响全局主题定制方式的破坏性变更。

5.4 移除 popperjs 依赖（v4.0.0-rc.3）

为减小安装体积，v4.0.0-rc.3 移除了popperjs依赖——不过从当前仓库 packages/vant/package.json 看，Vant 4 后续又引入了工作区内部的@vant/popperjs（源码见 packages/vant-popperjs/src/index.ts），将定位逻辑收归自研维护。

5.5 移除 less 源码以减小包体积（v4.0.0-beta.0）

v4.0.0-beta.0 移除了 less 源码文件，配合es/**/style/*与lib/**/style/*的sideEffects声明（见 package.json），使样式在按需引入时能被正确打包工具识别。

5.6 ES Module 改用 .mjs 扩展名（v4.0.0-alpha.4）

v4.0.0-alpha.4 起，ES Module 输出统一使用.mjs扩展名，当前仓库的module字段即为es/index.mjs（见 package.json）。

六、各版本要点速查表

以下表格汇总了 v4.0.0 正式版之后各版本的核心变更，便于快速检索：

七、版本记录中的工程实践信号

Changelog 不仅是功能清单，透过这些记录还能读出 Vant 团队的工程化管理方式：

7.1 国际化（i18n）持续扩充

Vant 4 在多个版本中持续新增语言包：阿拉伯语（v4.7.3）、塞尔维亚语（v4.6.4）、高棉语（v4.1.2）、荷兰语与蒙古语（v4.0.5）、世界语（v4.0.9）、丹麦语（v4.0.0-alpha.2）、老挝语（v4.0.0-alpha.1）等，并提供了useCurrentLang方法（v4.0.9）。当前语言包位于 packages/vant/src/locale/lang/（共 39 个语言文件），国际化入口见 packages/vant/src/locale/index.ts。

7.2 构建工具链演进：Vite → Rsbuild

从 v4.0.6（vite v4 升级）、v4.6.5（重写 vite-plugin-md）、v4.8.1（Rsbuild v0.2.2），到 v4.9.0（CLI 支持 Rsbuild 配置），可以看到 Vant 的文档站构建工具从 Vite 逐步迁移到 Rsbuild 的完整轨迹。这与 vant-cli 包（源码见 packages/vant-cli/src/cli.ts）的迭代密切相关。

7.3 测试体系升级：迁移到 Vitest/Rstest

v4.6.7 将测试运行器迁移到 vitest（PR #12206），v4.8.3 升级 vitest v1.1.3；当前仓库根目录使用rstest（见 packages/vant/package.json 的"test": "rstest run"与配置文件 rstest.config.mts）。每个组件目录下都有配套测试，例如 Calendar 的 switch-mode.spec.ts、BackTop 的 test 目录。

7.4 依赖管理自动化

从 v4.8.5 起引入 Renovate 配置、v4.8.6 起让 Renovate 自动更新package.json并分组 patch 更新、v4.9.0 升级到 pnpm v9，体现了依赖更新流程的自动化。

7.5 贡献者生态

Changelog 每版末尾都会列出"New Contributors"（新贡献者），这是开源项目对首次贡献者的认可机制，也方便社区成员追踪某个特性或修复的提出者。

八、结语：如何高效使用这份历史版本记录

这份 changelog 是理解 Vant 4 演进最重要的第一手资料。建议按以下方式使用：

1. 升级决策：升级前先核对目标版本所在行，确认是否包含你依赖的新特性（如需要switch-mode至少 v4.9.0），并避开 v4.8.9、v4.3.0 这类存在问题的版本；
2. 排障定位：遇到组件行为异常时，先在本表对应组件历史中检索是否有相关修复记录，再结合源码（packages/vant/src/<component>/）确认当前实现；
3. 源码佐证：每个新特性都可以在仓库源码中找到对应实现与测试，例如 Calendar 的 switch-mode.spec.ts、PickerGroup 的 PickerGroup.tsx，做到"记录可查、源码可证"。

注意：本 changelog 止于 v4.9.0（2024-05-02），此后版本的变更记录已迁移至 GitHub Releases，但 v4.9.0 之前的所有历史记录仍以本文档（changelog.en-US.md）为权威来源。

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant