DocBlockr安装失败主因是Package Control未初始化或channel_v3.json下载失败；需先验证Package Control是否生效，再手动配置本地channel路径并确保语法识别、编码及语言映射正确。
DocBlockr 插件安装失败的常见原因
直接搜“DocBlockr”装不上，大概率是 Package Control 没初始化成功，或者网络卡在下载 channel_v3.json。它不是插件本身的问题，而是底层通道没打通。
- 先确认
Package Control是否真已安装：按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Package Control: Settings – User，能打开配置文件就说明装好了 - 如果命令面板里搜不到任何
Package Control相关命令，说明没装成功——别重试，去控制台（Ctrl+`）粘贴官方安装代码再执行一次 - 装插件时卡在“Loading packages...”不动，八成是
channel_v3.json下载超时；手动下载该文件，放到本地路径（比如D:\sublime\channel_v3.json），然后在Package Control的Settings – User里加一行："channels": ["D:/sublime/channel_v3.json"]
安装 DocBlockr 后注释不生效怎么办
装完插件不代表能用，关键在于光标位置和触发方式。它只响应函数定义前的 /** + 回车，不是随便敲两行就能补全。
- 必须把光标放在函数声明正上方空白行，输入
/**再按Enter，不能写在函数内部、不能写在类方法中间空行、不能写在注释块里 - 支持的语言默认包括
JavaScript、PHP、Java、C++，但Python和TypeScript需要额外启用：在DocBlockr的Settings – User中加"jsdocs_language_map": {"source.python": "python", "source.ts": "javascript"} - 如果回车后只出来
/** */空壳，检查当前文件是否被识别为正确语法：右下角状态栏应显示JavaScript或PHP，而不是Plain Text；点一下切换，或按Ctrl+Shift+P→Set Syntax: JavaScript
自定义注释模板时容易忽略的参数细节
jsdocs_extra_tags 看似简单，但值里的占位符和顺序直接影响生成效果，尤其 {{datetime}} 和 ${1:[text]} 行为完全不同。
-
{{date}}和{{datetime}}是时间戳，前者只输出2026-07-23，后者带时分秒和时区，如2026-07-23T14:30:00+0800 -
${1:[copyright]}是可编辑占位符，光标会停在这里让你填内容；而@author ${1:Anonymous}会直接填入Anonymous并允许你覆盖，${2:xxx}则用于多光标跳转 - 删掉不需要的字段（比如
@version）不能只从jsdocs_extra_tags里去掉，还要关掉自动插入参数描述：设"jsdocs_function_description": false，否则仍会生成@param和@returns块 - 想让
@param显示类型（如@param {string} name），得开"jsdocs_spacer_between_sections": true并确保函数签名里有 JSDoc 风格的类型标注，否则类型会被忽略
中文环境下的乱码与编码陷阱
在 Windows 上用 GBK 编写的旧 PHP 文件里触发 DocBlockr，常出现注释里中文变问号或方块，根源不在插件，而在 Sublime 自身编码策略。
- 不要依赖“自动检测”，手动设编码：右键底部状态栏的
UTF-8→Reopen with Encoding → UTF-8；如果是 GBK 文件，选GBK，但注意 DocBlockr 默认只在 UTF-8 下可靠生成中文 - 如果保存后中文又变乱码，检查
Preferences → Settings – User是否有"default_encoding": "GBK"—— 这个配置会让新文件强制用 GBK，和 DocBlockr 内置的 UTF-8 时间格式冲突 - 真正稳定的方案是统一用 UTF-8（无 BOM）：在
Settings – User加"fallback_encoding": "UTF-8", "default_encoding": "UTF-8"，并确保所有项目文件都存为 UTF-8
实际用起来最麻烦的不是装插件，而是每次换项目都要重新核对语法识别模式、编码设置、以及 jsdocs_language_map 里有没有漏掉新语言。一个没配对，/** 回车就静音。
