KUSANAGIプラグイン1.4.9アップデートで文字コードエラーに遭遇した話
いつものように管理画面を開いたら、また来ました。
KUSANAGIプラグインの新しいバージョン「1.4.9」がリリースされました。
今回で4回目のアップデートだったので「もう余裕でしょ」と軽い気持ちで作業を始めたんですが……まさかのエラーに遭遇し、思わぬ沼にハマってしまいました。今回はその**原因究明から解決まで**を、超詳しく記録として残しておきます。
同じエラーで困っている人の助けになれば嬉しいです。
STEP1：モジュールのアップグレード（ここは順調）
まずはいつも通り、KUSANAGI本体とwpプラグインモジュールを更新します。
dnf upgrade kusanagi kusanagi-wp-plugins
途中で確認が来たら y を入力してEnterキーを押します。
結果はこちら。
アップグレード済み： kusanagi-9.10.5-1.el9.noarch kusanagi-wp-plugins-20260731-1.el9.noarch 完了しました！
ここまでは何の問題もなく、いつも通りスムーズでした。
STEP2：プロファイル更新でまさかのエラー発生
次に、各プロファイルのプラグインを更新するコマンドを実行します。
kusanagi update plugin mypc
すると、今まで見たことのないエラーが出ました。
kusanagi update: error: 'utf-8' codec can't decode byte 0x82 in position 3006: invalid start byte
念のためもう一度実行してみましたが、同じエラーが繰り返し出るだけ。これは一時的な不具合ではなく、**何かのファイルそのものに原因がある**ということが分かりました。
原因調査：怪しいファイルを探す
エラーメッセージの「utf-8 codec can’t decode」という部分から、**UTF-8ではない文字コードのファイルをKUSANAGIが読み込もうとして失敗している**ことが予想できます。
まずはプラグインフォルダの中を疑い、以下のコマンドで文字コードがおかしいPHPファイルがないか探してみました。
find /home/kusanagi/mypc/DocumentRoot/wp-content/plugins/ -name "*.php" -exec file {} \; | grep -v "UTF-8\|ASCII"結果、該当ファイルはナシ。 ここは犯人ではありませんでした。
続けて対象を広げて、テーマファイルや設定ファイルも含めて調べてみました。
find /home/kusanagi/mypc/DocumentRoot/wp-content/ -type f \( -name "*.php" -o -name "*.txt" -o -name "*.css" -o -name "*.json" \) -exec file {} \; | grep -v "UTF-8\|ASCII\|empty"出てきたのは翻訳ファイル（JSON）ばかりで、これらは正常なファイルなので無関係でした。
真犯人発覚：wp-config.phpが文字化けの原因だった
プラグインフォルダの中に犯人がいないなら……と思い、WordPressの心臓部である wp-config.php を疑ってみることにしました。
KUSANAGI環境では、セキュリティ上の理由で wp-config.phpはDocumentRootの一つ上の階層に配置されています。
file /home/kusanagi/mypc/wp-config.php
結果がこちら。
/home/kusanagi/mypc/wp-config.php: PHP script, Non-ISO extended-ASCII text, with CRLF line terminators
「Non-ISO extended-ASCII text」= UTF-8ではない文字コード（おそらくShift_JIS）で保存されていることが判明！
これまでのバージョンでは特に問題なく動いていたのですが、今回のKUSANAGIアップデートでファイルの読み込みチェックが厳しくなり、このファイルがひっかかるようになったようです。
解決方法：wp-config.phpをUTF-8に変換する
原因が分かれば対処は簡単です。文字コードをUTF-8に変換してあげればOK。
①念のためバックアップを取る
大事な設定ファイルなので、まず作業前に必ずバックアップを取ります。
cp /home/kusanagi/mypc/wp-config.php /home/kusanagi/mypc/wp-config.php.bak
②Shift_JISからUTF-8に変換する
iconv -f SHIFT_JIS -t UTF-8 /home/kusanagi/mypc/wp-config.php -o /tmp/wp-config-utf8.php
エラーなく実行できれば、元のファイルがShift_JISだったと判断でき、UTF-8への変換が正しく完了したということです。
③変換後の中身を確認する
念のため、文字化けしていないか中身をチェックします。
head -20 /tmp/wp-config-utf8.php
問題なく読める状態であればOKです。
④元のファイルを上書きする
変換したUTF-8版のファイルで、元のwp-config.phpを上書きします。
cp /tmp/wp-config-utf8.php /home/kusanagi/mypc/wp-config.php
上書き確認が出るので y を入力してEnterキーを押します。
再チャレンジ：今度こそ成功！
文字コードを直したところで、もう一度アップデートコマンドを実行します。
kusanagi update plugin mypc
結果はこちら。
Plugin files found in /home/kusanagi/mypc/DocumentRoot/wp-content/mu-plugins Installed KUSANAGI configure plugin is already the latest version. Nothing to do. Update KUSANAGI plugin 1.4.8 to 1.4.10 Update KUSANAGI Plus plugin 1.0.5 to 1.0.7 update completed.
「update completed.」が出て、無事に成功しました！
念のためブラウザでサイトの表示も確認しましたが、問題なく正常に表示されていました。
残りのプロファイルも忘れずに
原因が判明したので、残りのプロファイルも同じコマンドで一気に片付けます。
kusanagi update plugin nandemo
kusanagi update plugin webcss
こちらの2つは文字コードの問題がなかったため、エラーなく一発で成功しました。
今回のトラブルまとめ
| 項目 | 内容 |
|---|---|
| 発生したエラー | utf-8 codec can’t decode byte 0x82 in position 3006: invalid start byte |
| 原因 | wp-config.phpがShift_JISで保存されていた |
| 発覚のきっかけ | fileコマンドで文字コードを1つずつ調査 |
| 解決方法 | iconvコマンドでUTF-8に変換 |
| 影響範囲 | 2プロファイル中1つ（mypc）のみ |
| 所要時間 | 通常10分のところ、今回は30分ほど |
使用したコマンド一覧（コピペ用）
今回使ったコマンドをまとめておきます。同じエラーに遭遇した方はこの順番で試してみてください。
#モジュールのアップグレード dnf upgrade kusanagi kusanagi-wp-plugins #エラーが出たプロファイルのwp-config.phpの文字コードを確認 file /home/kusanagi/【プロファイル名】/wp-config.php #バックアップを取る cp /home/kusanagi/【プロファイル名】/wp-config.php /home/kusanagi/【プロファイル名】/wp-config.php.bak #UTF-8に変換 iconv -f SHIFT_JIS -t UTF-8 /home/kusanagi/【プロファイル名】/wp-config.php -o /tmp/wp-config-utf8.php #変換後の中身を確認 head -20 /tmp/wp-config-utf8.php #元のファイルを上書き cp /tmp/wp-config-utf8.php /home/kusanagi/【プロファイル名】/wp-config.php #再度プラグイン更新を実行 kusanagi update plugin 【プロファイル名】
【プロファイル名】の部分は、自分の環境に合わせて置き換えてください。
今回学んだこと
正直、最初にエラーが出たときは「うわ、やっちまったか」とかなり焦りました。何回コマンドを打ち直しても同じエラーが出るし、原因も全然見当がつかない。
でも一つずつ怪しい場所を潰していく地道な作業で、最終的に犯人（wp-config.phpの文字コード）にたどり着けました。探偵気分でちょっと楽しかったです。
たぶん昔、Windowsのメモ帳とかでwp-config.phpを一度編集したことがあって、その時にShift_JISで保存されちゃったんだと思います。心当たりのある方は要注意ですね。
同じような環境で運用されている方は、アップデート前に一度 file wp-config.php で文字コードをチェックしておくと安心かもしれません。
本来このアップデートでやるコマンドはシンプルに2ステップだけでした。
①モジュールのアップグレード
dnf upgrade kusanagi kusanagi-wp-plugins
②各プロファイルのプラグイン更新
kusanagi update plugin mypc kusanagi update plugin webcss
コメント