升级sublime text 4前须确认插件兼容性、按系统正确卸载重装、手动迁移非user目录配置、处理编码兼容问题,并检查私有插件。

升级前必须确认插件兼容性
Sublime Text 4 不再支持 Python 2.7 插件,所有插件必须迁移到 Python 3.8 运行时。如果你依赖的插件(比如 Package Control、SideBarEnhancements、Emmet)未更新到 ST4 兼容版本,升级后会直接失效或报错 ImportError: No module named 'urllib2' 这类典型 Python 2 痕迹。
实操建议:
- 打开命令面板(
Ctrl+Shift+P/Cmd+Shift+P),输入并运行Package Control: List Packages,记下已安装插件名 - 逐个访问对应 GitHub 仓库或 packagecontrol.io 页面,确认是否标注 “ST4 compatible” 或最新 release 时间在 2021 年 5 月之后
- 对不兼容插件,提前找替代方案(例如用
Origami替代部分SplitPane功能)或暂不升级
Windows/macOS/Linux 的正确升级路径
不能直接覆盖安装——Sublime Text 3 和 4 使用不同注册表项(Windows)、plist 文件(macOS)和配置目录(Linux),强行覆盖会导致设置丢失或启动失败。
实操建议:
- Windows:卸载 ST3 后,从 sublimetext.com/4 下载
sublime_text_build_4169_x64_setup.exe(以实际最新 build 为准),安装时勾选「Add to explorer context menu」和「Associate .txt files」 - macOS:删除
/Applications/Sublime Text.app,下载Sublime Text Build 4169.dmg,拖入 Applications;不要用brew cask install sublime-text(已弃用) - Linux:删除旧版
subl命令软链接,解压新 tarball 到/opt/sublime_text,重建链接:sudo ln -sf /opt/sublime_text/subl /usr/local/bin/subl
配置迁移要注意 Packages/User/ 之外的文件
用户设置(Preferences.sublime-settings)、按键绑定(Default (Linux).sublime-keymap)确实都在 Packages/User/ 下,但以下内容不会自动继承:
- 自定义构建系统若放在
Packages/MyBuild/(非 User 目录),需手动复制 - ST3 的
Cache/和Index/目录无用且可能引发卡顿,升级后首次启动会自动重建,但建议手动清空旧缓存目录(路径见Preferences → Browse Packages…上级目录) - 如果用过
sync_settings插件同步,确保其已更新至 v4.x,否则上传的 settings 可能含 ST3 特有字段(如"theme": "Soda Dark 3.sublime-theme"),导致 ST4 启动黑屏
升级后第一个要检查的错误是 UnicodeDecodeError: 'utf-8' codec can't decode byte
这是 ST4 默认强制 UTF-8 解码,而 ST3 对非 UTF-8 文件更宽容。当你打开一个 GBK 编码的中文 HTML 或旧日志文件时,ST4 会直接崩溃或显示乱码,控制台报错如上。
实操建议:
- 打开文件后立即按
Ctrl+Shift+P→ 输入Reopen with Encoding→ 选GBK或GB2312,再保存为 UTF-8 - 永久解决:在
Packages/User/Preferences.sublime-settings中添加:"fallback_encoding": "GBK",
(注意不是default_encoding) - 批量转换脚本可用
iconv -f GBK -t UTF-8 file.html > file_utf8.html,避免在 ST4 里反复切换编码
Packages/ 子目录里、没声明兼容性、也没人维护的私有 snippet 或 mini-plugin。动手前花十分钟查一遍 Package Control: List Packages 输出,比重装三次都管用。











