Sublime Text 4 插件必须适配内置 Python 3.3.6 环境，禁用 3.5+ 语法特性，兼容 API 变更（如 on_activated 初始化检查、view.run_command 参数校验），并确保 UTF-8 without BOM 编码与 plugin_host 正常运行。
Sublime Text 4 默认不支持 Python 3.8 插件，必须降级到 Python 3.3
Sublime Text 4 内置的 Python 解释器是 Python 3.3.6（Windows/macOS/Linux 均如此），不是你系统里装的 Python 3.8。所有插件代码、sublime_plugin 模块、API 调用都运行在这个封闭的 3.3 环境中。试图在插件里 import typing.TypedDict、pathlib.Path.is_relative_to() 或用 f-string 以外的格式化语法，会直接报 AttributeError 或 SyntaxError。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 不要在插件中调用
sys.version_info判断是否为 3.8——它永远返回(3, 3, 6) - 避免使用
Python 3.5+特性：如async def、yield from在 3.3 下不可用；__future__导入仅限print_function和unicode_literals - 路径操作统一用
os.path，别用pathlib（3.3 不含该模块）
如何让插件兼容 ST4 的 API 变更（尤其是 view.run_command() 和 on_activated）
ST4 对命令执行时机和事件触发顺序做了调整，最典型的是 on_activated 现在可能在 view 尚未完成初始化时就触发，导致 view.file_name() 返回 None 或 view.size() 为 0。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在
on_activated中加一层防御：用if view.window() and view.file_name()判断再执行逻辑 -
view.run_command("some_cmd", {"args": {...}})的args必须是 dict，不能是None或str，否则静默失败 - 自定义命令类必须继承
sublime_plugin.TextCommand或WindowCommand，且方法名必须为run(self, edit, **kwargs)；edit参数不可省略，哪怕没用到 - ST4 废弃了
sublime.Region.beg/end别名，只认begin()/end()方法
调试插件时看不到 print 输出？用 sublime.status_message() + console_show() 替代
ST4 的插件运行在独立子进程中，标准输出（print()）默认被丢弃，不会出现在 Sublime 控制台（Ctrl+`）。直接写日志文件又麻烦且不同步。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 临时调试用
sublime.status_message("debug: x={}".format(x))，消息会短暂显示在窗口右下角 - 需要详细日志时，在插件开头加
sublime.log_commands(True)和sublime.log_input(True)，然后打开控制台（Ctrl+`）观察命令流 - 想强制刷出控制台：执行
sublime.run_command("show_panel", {"panel": "console"}) - 注意：不要在
on_load或on_activated里高频调用status_message，会阻塞 UI
Package Control 安装的插件为何在 ST4 中失效？检查 plugin_host 进程和 .py 文件编码
常见现象是插件菜单不出现、快捷键无响应、命令面板搜不到命令——大概率是插件未适配 ST4 的插件宿主机制（plugin_host），或源码含 BOM/UTF-8 with BOM 编码。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 启动 ST4 后，在终端执行
ps aux | grep plugin_host（macOS/Linux）或任务管理器看是否存在plugin_host进程；若无，说明插件加载失败，需查Sublime Text.app/Contents/MacOS/plugin_host（macOS）权限是否可执行 - 用 VS Code 或 Notepad++ 打开插件的
.py文件，确认编码为UTF-8 without BOM；BOM 会导致ImportError: bad magic number - 插件根目录下必须有
__init__.py（哪怕为空），否则 ST4 不识别为有效包 - 禁用所有其他插件，只留待测插件，排除依赖冲突（例如某些插件仍调用已移除的
sublime.Region.cover()）
ST4 的插件开发本质是「在受限的 Python 3.3 沙箱里，用一套略有变动的 event 生命周期和同步命令模型做事」。最容易被忽略的是：你以为在用 Python 3.8 写代码，其实连 dict.keys() 返回的都不是 list 而是 dict_keys 对象——别想当然用索引取值。
