自定义WordPress插件GitHub自动更新功能失效求助

核心排查与修复步骤 #

1. 统一版本号格式 #

WordPress插件主文件头部的Version字段，必须和GitHub Release的tag格式完全匹配：

• 如果GitHub tag带v前缀（比如v1.0.1），要么把插件主文件的Version改成相同格式，要么在代码里自动移除tag的v前缀再做版本比较。
• 修复代码：在get_repository_info方法中添加前缀处理逻辑（见下文完整代码）。

2. 清除WordPress更新缓存 #

WordPress会缓存更新检查结果，手动触发更新：

• 进入后台「插件」页面，点击「检查更新」按钮
• 或者临时在my-plugin.php中添加代码强制清除缓存（测试完成后删除）：

  delete_site_transient( 'update_plugins' );
  

3. 验证GitHub Release状态 #

必须在GitHub上创建正式发布的Release（不能是草稿或预发布版本），否则GitHub API不会返回该版本信息。

4. 检查GitHub API请求有效性 #

• 公有仓库可以直接访问https://api.github.com/repos/你的用户名/你的仓库/releases，确认能返回Release数据
• 私有仓库要确保访问令牌（token）拥有repo权限，且代码中填写的token正确

5. 修复代码冗余与逻辑漏洞 #

原代码中get_repository_info有重复的$args = array();定义，且缺少对GitHub响应有效性的判断，这些都可能导致更新检测失效。

修改后的完整代码 #

update.php（修复版） #

<?php

class toolkit_Updater {

    private $file;
    private $plugin;
    private $basename;
    private $active;
    private $username;
    private $repository;
    private $authorize_token;
    private $github_response;

    public function __construct( $file ) {
        $this->file = $file;
        add_action( 'admin_init', array( $this, 'set_plugin_properties' ) );
        return $this;
    }

    public function set_plugin_properties() {
        $this->plugin   = get_plugin_data( $this->file );
        $this->basename = plugin_basename( $this->file );
        $this->active   = is_plugin_active( $this->basename );
    }

    public function set_username( $username ) {
        $this->username = $username;
    }

    public function set_repository( $repository ) {
        $this->repository = $repository;
    }

    public function authorize( $token ) {
        $this->authorize_token = $token;
    }

    private function get_repository_info() {
        if ( is_null( $this->github_response ) ) {
            $args = array();
            $request_uri = sprintf( 'https://api.github.com/repos/%s/%s/releases', $this->username, $this->repository );
            
            if( $this->authorize_token ) {
                  $args['headers']['Authorization'] = "bearer {$this->authorize_token}";
            }

            $response = json_decode( wp_remote_retrieve_body( wp_remote_get( $request_uri, $args ) ), true );

            if( is_array( $response ) ) {
                $response = current( $response );
                // 移除tag的v前缀，确保版本号比较一致
                if ( isset( $response['tag_name'] ) ) {
                    $response['tag_name'] = ltrim( $response['tag_name'], 'v' );
                }
            }

            $this->github_response = $response;
        }
    }

    public function initialize() {
        add_filter( 'pre_set_site_transient_update_plugins', array( $this, 'modify_transient' ), 10, 1 );
        add_filter( 'plugins_api', array( $this, 'plugin_popup' ), 10, 3);
        add_filter( 'upgrader_post_install', array( $this, 'after_install' ), 10, 3 );
        
        add_filter( 'upgrader_pre_download', function() {
            add_filter( 'http_request_args', [ $this, 'download_package' ], 15, 2 );
            return false;
        } );
    }

    public function modify_transient( $transient ) {
        if( property_exists( $transient, 'checked') && $checked = $transient->checked ) {
            $this->get_repository_info();
            
            // 确保GitHub响应有效且版本号存在
            if ( ! isset( $this->github_response['tag_name'] ) || ! isset( $checked[ $this->basename ] ) ) {
                return $transient;
            }

            $out_of_date = version_compare( $this->github_response['tag_name'], $checked[ $this->basename ], 'gt' );

            if( $out_of_date ) {
                $new_files = $this->github_response['zipball_url'];
                $slug = current( explode('/', $this->basename ) );

                $plugin = array(
                    'url' => $this->plugin["PluginURI"],
                    'slug' => $slug,
                    'package' => $new_files,
                    'new_version' => $this->github_response['tag_name']
                );

                $transient->response[$this->basename] = (object) $plugin;
            }
        }

        return $transient;
    }

    public function plugin_popup( $result, $action, $args ) {
        if( ! empty( $args->slug ) && $args->slug == current( explode( '/' , $this->basename ) ) ) {
            $this->get_repository_info();
            
            if ( ! isset( $this->github_response['tag_name'] ) ) {
                return $result;
            }

            $plugin = array(
                'name'              => $this->plugin["Name"],
                'slug'              => $this->basename,
                'version'           => $this->github_response['tag_name'],
                'author'            => $this->plugin["AuthorName"],
                'author_profile'    => $this->plugin["AuthorURI"],
                'last_updated'      => $this->github_response['published_at'],
                'homepage'          => $this->plugin["PluginURI"],
                'short_description' => $this->plugin["Description"],
                'sections'          => array(
                    'Description'   => $this->plugin["Description"],
                    'Updates'       => $this->github_response['body'] ?? '暂无更新说明',
                ),
                'download_link'     => $this->github_response['zipball_url']
            );

            return (object) $plugin;
        }
        return $result;
    }
    
    public function download_package( $args, $url ) {
        if ( null !== $args['filename'] && $this->authorize_token ) { 
            $args = array_merge( $args, array( "headers" => array( "Authorization" => "token {$this->authorize_token}" ) ) );
        }
        
        remove_filter( 'http_request_args', [ $this, 'download_package' ] );
        return $args;
    }

    public function after_install( $response, $hook_extra, $result ) {
        global $wp_filesystem;
        $install_directory = plugin_dir_path( $this->file );
        
        // 先清理旧插件目录
        if ( $wp_filesystem->exists( $install_directory ) ) {
            $wp_filesystem->delete( $install_directory, true );
        }
        
        $wp_filesystem->move( $result['destination'], $install_directory );
        $result['destination'] = $install_directory;

        if ( $this->active ) {
            activate_plugin( $this->basename );
        }

        return $result;
    }
}

my-plugin.php（替换占位符） #

<?php
/*
Plugin Name: 你的插件名称
Plugin URI: 你的插件网址
Description: 插件描述
Version: 1.0.0
Author: 你的名字
Author URI: 你的网址
License: GPL2
*/

if( ! class_exists( 'toolkit_Updater' ) ){
    require( plugin_dir_path( __FILE__ ) . 'update.php' );
}

// 替换为你的GitHub信息
$updater = new toolkit_Updater( __FILE__ );
$updater->set_username( '你的GitHub用户名' );
$updater->set_repository( '你的仓库名称' );
// 公有仓库可注释此行，私有仓库需填写带repo权限的令牌
// $updater->authorize( '你的GitHub访问令牌' );
$updater->initialize();

// 测试时添加此行强制清除缓存，测试完成后删除
// delete_site_transient( 'update_plugins' );

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