升级Sublime Text 4前须确认插件兼容性、按系统正确卸载重装、手动迁移非User目录配置、处理编码兼容问题，并检查私有插件。
升级前必须确认插件兼容性
这里有个关键点需要先搞清楚：Sublime Text 4 彻底告别了 Python 2.7 的运行时环境。这意味着，所有依赖旧版 Python 的插件，如果没及时跟进适配 Python 3.8，升级后就会直接“罢工”。你可能会遇到像 ImportError: No module named 'urllib2' 这类典型的 Python 2 时代错误，像 Package Control、SideBarEnhancements 这类核心插件如果版本不对，整个编辑器的扩展功能就可能瘫痪。
那具体该怎么操作呢？其实就三步：
- 首先，打开命令面板（快捷键
Ctrl+Shift+P或Cmd+Shift+P），运行Package Control: List Packages，把已安装的插件名单完整地列出来。 - 然后，逐个去它们的 GitHub 仓库或者 packagecontrol.io 页面看一眼。重点确认是否明确标注了 “ST4 compatible”，或者最新版本的发布时间是否在 2021年5月（ST4正式发布）之后。
- 最后，对于确认不兼容又暂时找不到更新的插件，就得提前想好备用方案了。比如，有些窗格管理功能，或许可以用
Origami来替代旧的SplitPane。如果找不到合适的替代品，那可能就得慎重考虑是否要暂缓升级了。
Windows/macOS/Linux 的正确升级路径
千万别直接覆盖安装！Sublime Text 3 和 4 在系统层面的注册信息、配置文件路径都是独立的，强行覆盖大概率会导致设置丢失，甚至启动失败。正确的做法是“先卸载，再全新安装”。
不同系统的操作路径略有不同：
- Windows用户：先从控制面板正常卸载 Sublime Text 3。然后，去官网（sublimetext.com/4）下载最新的安装包（比如
sublime_text_build_4169_x64_setup.exe，具体版本号以官网为准）。安装时，记得勾选“添加到资源管理器右键菜单”和“关联 .txt 文件”这些实用选项。 - macOS用户：直接把
/Applications目录下的旧版Sublime Text.app拖到废纸篓。接着下载官网的.dmg镜像文件，把新的应用拖进Applications文件夹即可。注意，别再用brew cask install sublime-text这个已经弃用的命令了。 - Linux用户：操作稍微“手工”一些。先删除旧的
subl命令软链接，然后把从官网下载的 tarball 包解压到/opt/sublime_text目录。最后，重建一个全局软链接：sudo ln -sf /opt/sublime_text/subl /usr/local/bin/subl，这样在终端就能直接用subl命令启动了。
配置迁移要注意 Packages/User/ 之外的文件
大部分用户都知道，像 Preferences.sublime-settings（用户设置）和 Default (Linux).sublime-keymap（按键绑定）这些核心配置文件，都存放在 Packages/User/ 目录下，它们通常会被新版本继承。但问题往往出在那些“隐藏”在别处的文件上。
下面这几类内容，需要你额外留心，手动处理：
- 自定义构建系统：如果你当初把自定义的构建系统文件放在了
Packages/MyBuild/这类非 User 的自建目录里，那么升级后它们不会自动出现，需要你手动复制到新版对应的目录中。 - 缓存与索引目录：ST3 留下的
Cache/和Index/目录对新版不仅没用，还可能引发卡顿。虽然 ST4 首次启动时会自动重建，但为了保险起见，建议手动清空旧目录。路径可以通过Preferences → Browse Packages…打开，然后返回其上级目录找到。 - 配置同步插件：如果你用过
sync_settings这类插件来同步配置，务必确保它已经更新到支持 ST4 的版本（如 v4.x）。否则，从云端拉取的旧版设置里可能包含 ST3 特有的字段（例如"theme": "Soda Dark 3.sublime-theme"），这可能导致 ST4 启动时直接黑屏。
升级后第一个要检查的错误是 UnicodeDecodeError: 'utf-8' codec can't decode byte
这是升级后最容易碰到的“当头一棒”。Sublime Text 4 对编码的处理比 ST3 严格得多，默认强制使用 UTF-8 解码文件。当你尝试打开一个用 GBK 编码的中文 HTML 文件，或者一些遗留的旧日志文件时，编辑器要么直接崩溃，要么显示一堆乱码，控制台里就会抛出这个解码错误。
遇到这个问题别慌，有现成的解决办法：
- 临时解决（单文件）：打开文件后，立刻按
Ctrl+Shift+P调出命令面板，输入Reopen with Encoding，然后选择正确的编码，比如GBK或GB2312。文件正常显示后，再另存为 UTF-8 格式即可。 - 永久解决（全局设置）：一劳永逸的方法是修改用户设置。打开
Packages/User/Preferences.sublime-settings文件，添加一行："fallback_encoding": "GBK",
注意，这里的关键是fallback_encoding，而不是default_encoding。这个设置会让 ST4 在无法用 UTF-8 解码时，自动尝试使用 GBK 编码。 - 批量转换（治本之策）：如果手头有一大批历史遗留的非 UTF-8 文件，建议在升级前就用脚本批量转换。比如在终端使用
iconv -f GBK -t UTF-8 file.html > file_utf8.html命令，可以避免在编辑器里一个个手动操作。
话说回来，ST4 在 UI 渲染流畅度和多光标处理性能上的提升是实实在在的。但经验表明，真正阻碍升级过程的，往往不是软件本身，而是那些藏在 Packages/ 各个角落、没有明确声明兼容性、甚至已经无人维护的私有代码片段或迷你插件。所以，动手升级前，花上十分钟，仔细检查一遍 Package Control: List Packages 列出的每一个条目，这个准备工作，往往比事后重装三遍都要管用。
