wp plugin verify-checksums はスキップがあっても Success を返します。終了コードは0でした

wp plugin verify-checksums --all は、照合できなかったプラグインがあっても成功で終わります。終了コードは0です。

CIで終了コードだけを見ていると、Pro版のように WordPress.org にないプラグインが混ざっていても、そのまま通ります。

先に断っておくと、このコマンドの存在も使い方も、公式ドキュメントに書いてあります。ここで書くのは、ソースを読んで確かめた判定の分岐と、それを踏まえて書いた検査スクリプトです。スクリプトは dash と bash の両方で、分岐を5通り確かめました。

出力は4通りあります

wp-cli/checksum-command のソースを読みました。最終的なメッセージは、wp-cli 本体の report_batch_operation_results() が組み立てています。

分岐はこうなっていました。

状況	出力	終了コード
全部照合できた	Success: Verified 7 of 7 plugins.	0
スキップがあった	Success: Verified 6 of 7 plugins (1 skipped).	0
一部が食い違った	Error: Only verified 6 of 7 plugins (1 failed).	1
全部食い違った	Error: No plugins verified (7 failed).	1

2行目が、今回の話です。

Error になるのは、チェックサムが実際に食い違ったときだけでした。照合する相手が見つからずにスキップしたものは、失敗として数えられません。メッセージには (1 skipped) と出ますが、終了コードは成功と同じ0です。

ソースでいうと、ここです。

$failures  = count( array_unique( array_column( $this->errors, 'plugin_name' ) ) );
$successes = $total - $failures - $skips;

スキップは $failures に入らず、$skips として別に数えられます。そして report_batch_operation_results() は、$failures が0なら WP_CLI::success() を呼びます。

なぜスキップが出るのか

照合の相手は、WordPress.org にあるチェックサムです。

WordPress.org で配布していないプラグインは、比べる相手がありません。そのときは警告を出して、スキップします。

Warning: Could not retrieve the checksums for version 1.10.12 of plugin prime-cache-pro, skipping.

自作の Pro 版、他社の有料プラグイン、社内で作ったもの。どれもこうなります。

わたしが引っかかったのは、自分で管理しているサイトでこれを使ったときでした。最後の行が Success だったので、そのまま「異常なし」と受け取りかけました。1本、照合されていないものが入っていました。

検査スクリプト

N と M が一致しないときだけ止めるようにしました。

#!/bin/sh
# WordPress.org にあるプラグインが、すべて照合されたかを確かめる。
# wp plugin verify-checksums はスキップがあっても Success（終了コード0）を返すので、
# 「Verified N of M」の N と M を比べて、一致しなければ止める。
#
# 使い方:
#   ./verify-plugins.sh                              # 全部照合
#   ./verify-plugins.sh --exclude=my-pro-plugin      # 照合できないと分かっているものを外す
set -u

out=$(wp plugin verify-checksums --all "$@" 2>&1)
status=$?
printf '%s\n' "$out"

# チェックサムの不一致は wp 自身が Error（終了コード1）で返す
if [ "$status" -ne 0 ]; then
    echo "NG: チェックサムが一致しないプラグインがあります" >&2
    exit "$status"
fi

# 成功行から N と M を取り出す（例: Success: Verified 6 of 7 plugins (1 skipped).）
line=$(printf '%s\n' "$out" | grep -E '^Success: Verified [0-9]+ of [0-9]+ ' || true)
if [ -z "$line" ]; then
    echo "NG: 結果の行を読み取れませんでした" >&2
    exit 3
fi

n=$(printf '%s\n' "$line" | sed -E 's/^Success: Verified ([0-9]+) of ([0-9]+) .*/\1/')
m=$(printf '%s\n' "$line" | sed -E 's/^Success: Verified ([0-9]+) of ([0-9]+) .*/\2/')

if [ "$n" -ne "$m" ]; then
    echo "NG: $m 本中 $n 本しか照合されていません（$((m - n)) 本スキップ）" >&2
    echo "    照合できないと分かっているものは --exclude= で外してください" >&2
    exit 2
fi

echo "OK: $m 本すべて照合しました"

#!/bin/sh で書いて、ShellCheck を無警告で通しています。

終了コードを3つに分けた

まず、wp 自身が失敗を返したら、その終了コードをそのまま返します。チェックサムが食い違ったときです。

それから、N と M が一致しなければ 2 を返します。スキップがあったときです。

最後に、結果の行が読めなければ 3 を返します。WP-CLI のメッセージの形が変わったときに、黙って通さないためです。

CI で「何で止まったか」を分けて扱えるように、番号を分けました。

--exclude= で、分かっているものを外す

自作の Pro 版のように、照合できないと最初から分かっているものがあります。毎回スキップで止まると困るので、外せるようにしてあります。

$ ./verify-plugins.sh --exclude=prime-cache-pro
Success: Verified 6 of 6 plugins.
OK: 6 本すべて照合しました

--exclude= は wp-cli 側のオプションで、そのまま渡しています。外したものは総数からも消えるので、N と M がそろいます。

外したものは照合されていない、ということは変わりません。自作のものなら、手元のリポジトリと diff を取れば確かめられます。

$(...) の終了コード

out=$(wp ...) のあとに $? を見ています。

変数への代入でも、コマンド置換があれば、その終了コードが $? に入ります。POSIX でそう決まっています。念のため dash と bash の両方で確かめました。

5通り確かめた結果

実際の WP-CLI をこの環境で走らせられなかったので、ソースの分岐をそのまま再現した偽の wp を作って、スクリプトを通しました。

状況	wp 単体の終了コード	このスクリプト
全部照合できた	0	0
スキップがあった	0	2
一部が食い違った	1	1
全部食い違った	1	1
--exclude= で外した	0	0

2行目だけ、結果が変わります。ここを拾うために書いたスクリプトです。

dash 0.5.12 と bash 5.2.21 の両方で、5通りとも同じ結果でした。

スキップしたときのメッセージは、こう出ます。

Success: Verified 6 of 7 plugins (1 skipped).
NG: 7 本中 6 本しか照合されていません（1 本スキップ）
    照合できないと分かっているものは --exclude= で外してください

残っていること

(1 skipped) の文言に頼っていない点は、少し気にしています。

このスクリプトは N と M の数字だけを見ています。wp-cli が将来メッセージの形を変えたら、結果の行が読めなくなって、終了コード3で止まります。黙って通ることはありませんが、その時点で直す必要があります。

もう1つ。プラグインの照合は、プラグインのディレクトリしか見ません。コアは wp core verify-checksums、uploads に置かれた不審なファイルは別に探す必要があります。このスクリプトが保証するのは、WordPress.org にあるプラグインのファイルが元と同じ、ということまでです。

参考

• wp-cli/checksum-command src/Checksum_Plugin_Command.php
• wp-cli/wp-cli php/utils.php の report_batch_operation_results()

どちらも GitHub で読めます。メッセージの形はバージョンで変わりうるので、使っている WP-CLI のソースで確かめてください。

---

ふだんはraplsworks.comで、WordPressプラグイン開発やClaude Codeまわりのことを書いています。