Sublime Text 4 必须用 DoxyDoxygen 替代失效的 DocBlockr，并手动适配 Jinja2 模板、触发逻辑及语法模式；否则注释空、错、漏。需检查 Package Control 状态、快捷键上下文、模板变量语法、JS 解构参数支持、中文编码与字体，以及 TypeScript/Python/C++ 高级类型的手动解析扩展。
Sublime Text 4 用户别装 DocBlockr，它已彻底失效；必须用 DoxyDoxygen，并手动适配 Jinja2 模板和触发逻辑，否则生成的注释空、错、漏——这不是配置问题，是插件底层与 ST4 运行时不兼容。
DoxyDoxygen 安装失败或搜不到？先确认 Package Control 状态
搜不到 DoxyDoxygen，大概率不是插件下架了，而是 Package Control 本身没响应。常见表现：命令面板里输 Package Control: Install Package 后无反应，或列表为空。
- 打开
Preferences → Package Settings → Package Control → Settings，检查installed_packages是否包含"Package Control"，且没被注释掉 - 终端执行
subl --debug（macOS/Linux）或查看 Sublime 控制台（Ctrl+`），看是否有Package Control: Error loading package类报错 - 若确认异常，直接重装 Package Control：删掉
Packages/Package Control目录，再用官方安装脚本（Python 3.8+ 兼容版）重新拉取
快捷键没反应？检查语法模式和光标位置
按 Ctrl+Alt+D（Windows/Linux）或 Cmd+Alt+D（macOS）无输出，不是快捷键冲突就是上下文不满足。
- 右下角状态栏必须显示具体语言模式，如
Python、JavaScript、C++—— 若是Plain Text或HTML，插件完全静默 - 光标必须严格落在函数/方法定义行上，例如：
def process_data(items: list) -> dict:或int calculate(int a, int b);，不能在空行、注释行或函数体内部 - 若用了 TypeScript 或 Babel 插件，它们常劫持语法高亮，临时切换回原生
JavaScript模式再试
生成的注释字段全空或参数缺失？模板语法和配置要重写
DoxyDoxygen 用 Jinja2，和旧版 DocBlockr 的 ${1:description} 完全不兼容。直接复用老模板会导致字段跳过、整行消失。
- 变量写法必须改：用
{description}，不是${1:description}；循环参数必须写成{% for param in params %}@param {param.name} {param.type}{% endfor %} - JS 解构参数（如
function load({ timeout = 5000, retries })）默认不解析，需在DoxyDoxygen.sublime-settings中开启："js_extract_destructured_params": true - 想让
@return总是出现（哪怕函数无返回值），得加判断：{% if return_type %}@return {return_type}{% endif %}
中文作者名显示方块或乱码？fallback_encoding 不是唯一原因
Windows 上 @author 张三 显示为方块，常被归因为编码设置错误，但实际更可能是字体或 Sublime 内部渲染链路问题。
- 确认
Preferences → Settings中"fallback_encoding": "UTF-8"已设 - 检查当前视图字体是否支持中文（如用
Consolas就容易出方块，换成Fira Code或JetBrains Mono） - 若仍无效，在
DoxyDoxygen.sublime-settings中显式添加："encoding": "UTF-8"，并重启 Sublime（仅此设置生效需重启）
真正难搞的不是装插件，是让模板里的 {% if %} 判断能准确识别 TypeScript 的联合类型、Python 的 Optional[str] 或 C++ 模板参数——这些需要手动扩展解析逻辑，官方模板默认只覆盖基础语法。别指望一键完美，得边用边调。
