Sublime配置WordPress主题开发增强包_强化函数参考与结构预览

Sublime Text 3 的 WordPress 插件必须启用 auto_complete_selector 才能触发补全

Sublime Text 3 的 WordPress 插件必须启用 auto_complete_selector 才能触发补全

是不是遇到过这种情况？插件明明装好了，可敲 add_action 或者 get_template_part 的时候，期待中的提示框就是不出来。别急着怀疑插件，问题很可能出在 Sublime Text 自己身上。这款编辑器默认只在特定的语法作用域里才激活自动补全功能。而 WordPress 插件的补全规则，依赖于 PHP 文件被准确识别为 source.php 作用域。麻烦在于，默认设置常常把范围限定在 source 里，偏偏漏掉了像 header.php 这类主题文件中常见的混合语法场景——它们通常被识别为 text.html.basic。

怎么解决？其实就一步：

• 打开 Preferences → Settings – User，确保配置里包含这一行："auto_complete_selector": "source, text"
• 记住，如果你的主题文件是 HTML 里嵌着 PHP（比如经典的 index.php），只写 "source" 是没用的；必须用 "source, text" 才能全覆盖。
• 改完配置不用重启编辑器，但最好重新打开一下正在编辑的 PHP 文件，否则缓存可能来不及刷新。
• 验证成功与否很简单：在 functions.php 里试着输入 get_，如果立刻弹出 get_header、get_template_directory_uri 这些选项，那就说明配置生效了。

completions/ 和 snippets/ 是两套机制，别混淆用途

打开插件包，你会看到两个核心目录：completions/ 和 snippets/。可别把它们弄混了，这是两套完全不同的“翻跟斗”。completions/ 提供的是函数名连带参数占位符的实时补全，你按 Tab 键可以在参数之间跳转填充。而 snippets/ 是代码片段库，你输入预设的缩写（比如 aa），再按 Tab，它会直接展开成一段完整的代码结构，例如 add_action('hook', function() {});。它们的触发条件、编辑逻辑和维护方式都截然不同。

这里有几个新手常踩的坑：

• 以为补全失效了，其实是把 snippet 的触发方式搞错了。你想展开 add_action 片段，却打了 adda，而插件定义的缩写可能是更短的 aa。
• 试图通过修改 completions/add_action.sublime-completion 文件里的 contents 字段来改变函数行为，这是行不通的。那个字段只控制补全时参数的显示顺序，真正的函数执行逻辑，还得靠你老老实实写在 functions.php 里。
• 从 VS Code 转过来的开发者，容易把它类比成 Emmet，但 Sublime 的 snippet 没那么“智能”。它不支持根据当前编码上下文做动态判断，比如，它不会自动识别你正在一个 class 内部，从而给你补上 $this->。

WordPress 插件对 theme.json 和 FSE 区块模式无补全支持

时间来到2024年，主流主题开发早已转向全站编辑（FSE）模式，大量逻辑迁移到了 theme.json 配置文件，或者 patterns/ 目录下的区块模板里。但这里有个关键的现实问题：目前 Sublime Text 上的 WordPress 插件（即便是最新版本），其核心仍然是基于 WordPress 6.0 到 6.4 时期的 PHP 函数体系构建的。这意味着，它对 JSON Schema、block.json 结构，或者 wp:query 这类区块标签，完全“不认识”。

带来的直接影响就是：

• 你在 theme.json 里敲 "settings" 时，别指望会有属性提示弹出来。这部分工作，得依靠官方文档，或者切换到 VS Code 这类对 JSON Schema 支持更好的编辑器。
• 在 patterns/homepage.php 文件里写 wp:post-title 标签时，同样不会有补全提示，也无法实现跳转到定义。
• 如果你的主题同时包含传统的 PHP 模板和新的 FSE 模板，一个比较实际的策略是：将 theme.json 和 patterns/ 目录交给 VS Code 处理，而 PHP 模板文件继续留在 Sublime，搭配 WordPress 插件使用。

插件函数列表停在 WordPress 6.4，新 API 如 wp_register_preset 不会出现

需要明确一个事实：当前流传最广的那个 Sublime WordPress 插件（比如那个号称包含 2909 个函数的版本），其内置的函数数据源，更新截止到 WordPress 6.4 就停止了。因此，WordPress 6.5 及后续版本引入的一系列新 API，比如性能相关的 wp_register_preset，或者新的样式引擎钩子 wp_theme_json_data_default，都不会出现在补全列表里。这不是你配置有问题，纯粹是插件数据没跟上。

面对这个情况，可以这么做：

• 需要查询新函数时，第一选择是打开本地 WordPress 安装目录下的 wp-includes/theme-templates.php 等核心文件查看，或者直接访问官方的开发者参考网站。
• 千万不要仅凭编辑器有没有补全提示，来判断一个函数是否存在或可用。例如，wp_register_preset 是 6.5 才加入的，在基于 6.4 数据源的插件里当然搜不到，但这不代表这个函数无效。
• 如果你长期从事 FSE 主题开发，建议将 WP CLI 命令行工具作为辅助。用 wp theme list 检查状态，用 wp rewrite structure 验证规则，这些运行时验证比静态的编辑器提示更可靠。

最后，还有一个极易被忽略的关键点：插件的补全功能，本质上是静态的文本匹配。它只管给你弹出函数名，可不管你这个函数用在这里合不合适。举个例子，wp_enqueue_script 如果错误地放在 init 钩子里调用是会出问题的，但插件才不管这些，它照样高高兴兴地给你补全上——它可不会智能到去校验你到底是把它写在了 functions.php 的顶层，还是正确地放在了 add_action('wp_enqueue_scripts', ...) 的回调函数里。