如何为自研非WP托管的WordPress Plugin实现自动更新？

Hey，我之前给客户做自托管插件更新时也碰到过一模一样的情况——照着教程写了代码，但点「检查更新」永远显示“所有内容均为最新版本”。折腾了好一阵才摸清楚几个容易忽略的坑，结合Bitbucket这类私有托管的场景，给你分享下经验：

先排查最容易踩的版本号对比坑 #

WordPress判断更新的核心逻辑是本地插件版本号和远程API返回的版本号的对比，这里很容易出问题：

• 确保远程返回的new_version确实比你当前安装的插件版本高（比如本地是1.0.0，远程得是1.0.1或1.1.0），而且版本号格式要完全一致（别一个是1.0一个是1.0.0，或者带beta后缀的格式不统一）。
• 有些教程里的代码会把远程版本号硬写死，记得改成动态读取的（比如从远程JSON文件或者仓库标签里获取）。

私有托管的权限必须搞定 #

如果用Bitbucket私有仓库，直接用公开链接肯定拿不到文件，得配置权限：

• 用Bitbucket的个人访问令牌（PAT）或者App Password，把权限加到下载链接里，格式类似：https://{你的用户名}:{PAT令牌}@bitbucket.org/你的仓库名/插件压缩包路径.zip。
• 要是你自己写更新API端点，也可以在请求Bitbucket资源的时候，给HTTP请求加上Authorization: Bearer {你的PAT}头，这样不用把令牌暴露在URL里。

确保更新API的响应格式完全合规 #

WordPress的更新检查接口必须返回特定结构的JSON，少一个字段或者格式错了都会导致识别失败，这里给个最简示例：

<?php
// 放在你的私有服务器或者Bitbucket静态文件里作为更新端点
header('Content-Type: application/json');
echo json_encode([
    'slug' => '你的插件唯一标识（和主文件里的Text Domain一致最好）',
    'new_version' => '1.1.0',
    'package' => '上面带权限的插件压缩包下载链接',
    'url' => '插件的说明页面链接（可选）'
]);

你可以直接在浏览器里访问这个端点，看看返回的JSON有没有语法错误，字段名有没有写错（比如把new_version写成version就不行）。

简化流程的工具推荐 #

不想自己从头写钩子逻辑的话，可以用现成的开源PHP类库，它们已经封装好了WordPress的pre_set_site_transient_update_plugins和plugins_api钩子，你只需要配置仓库地址、令牌和版本信息就行，能省不少事。

排查技巧 #

• 打开WordPress的调试模式（在wp-config.php里设WP_DEBUG = true），看wp-content/debug.log里有没有更新相关的错误，比如远程请求失败、权限被拒、JSON解析错误，这些日志能直接帮你定位问题。
• 用Postman或者curl测试你的更新端点和下载链接，确保能正常访问到JSON和压缩包。

我当时就是因为把远程版本号写成了1.0而本地是1.0.0，导致WordPress认为版本一致，改完格式就正常触发更新了，你可以先从版本号和响应格式查起！

内容的提问来源于stack exchange，提问作者Jonny