Yazi v0.4.0 版本迁移指南与技术解析

Yazi 是一款现代化的终端文件管理器，在 v0.4.0 版本中进行了多项重大更新。本文将为开发者详细介绍这些变更内容，帮助用户顺利完成版本迁移。

命令系统重构

v0.4.0 版本对命令系统进行了语义化重构，为未来的功能扩展预留了空间。最显著的变化是将原先的 select 命令重命名为 toggle，同时将 select_all 命令也相应改为 toggle_all。这种命名更加准确地反映了命令的实际功能——切换文件的选择状态。

在键位配置文件中，用户需要将原有的 <Space> 键绑定从 select --state=none 更新为简单的 toggle。对于全选功能，原先的 <C-r> 和 <C-a> 快捷键也需要相应调整，新的语法更加简洁直观。

文件时间属性标准化

新版本对文件时间属性的命名进行了规范化处理，解决了原先术语使用不准确的问题。具体变更包括：

• 将 ctime 统一改为 btime（birth time），更准确地表示文件创建时间
• modified 改为 mtime（modification time），表示最后修改时间
• accessed 改为 atime（access time），表示最后访问时间

这一变更影响了多个场景下的配置，包括排序命令、行模式显示以及Lua插件API中的属性访问。开发者需要检查所有相关配置，确保使用新的标准术语。

文件类型识别改进

v0.4.0 优化了文件类型识别系统，移除了MIME类型中的冗余 x- 前缀。这一变更使得Yazi能够更好地兼容不同版本的 file 命令工具，提供更一致的行为。

在主题和打开行为配置中，所有以 application/x- 开头的MIME类型都需要简化为 application/ 开头。例如，压缩文件类型的配置需要相应更新。

插件系统增强

新版本对插件系统进行了多项改进，提升了开发体验：

1. 移除了 plugin 命令的 --sync 选项，简化了插件调用语法
2. 重构了任务参数传递机制，将任务信息从 self 转移到专门的 job 参数
3. 统一了错误处理，使用更具可读性的 Error 类型替代数字错误码

这些变更使得插件开发更加规范，同时也为未来的功能扩展奠定了基础。插件开发者需要检查现有代码，按照新的API规范进行调整。

主题系统升级

v0.4.0 的主题系统获得了多项增强：

1. 引入了明暗主题自动切换支持，使用 dark 和 light 替代原先的 use 配置
2. 简化了颜色配置，合并了冗余的 fg_dark 和 fg_light 属性
3. 改进了样式系统，为不同UI元素提供了更精细的控制

这些改进使得主题开发更加灵活，同时也简化了配置语法。主题维护者需要相应更新主题文件。

底层依赖变更

在依赖方面，v0.4.0 用 ffmpeg 和 ffprobe 替代了原先的 ffmpegthumbnailer 作为视频预览后端。这一变更提供了更强大的视频处理能力，但同时也意味着打包时需要确保新的依赖可用。

总结

Yazi v0.4.0 是一次重大更新，带来了多项改进和优化。虽然这些变更可能会带来短暂的迁移成本，但它们为系统的长期发展奠定了更好的基础。建议所有用户仔细阅读本文档，按照指导完成配置更新，以充分利用新版本带来的各项优势。

对于插件开发者，特别需要注意Lua API的变更，确保代码兼容新的参数传递方式和属性命名。系统管理员则需要检查打包配置，确保满足新的依赖要求。通过这些准备工作，用户可以顺利过渡到v0.4.0，享受更强大、更稳定的文件管理体验。