Jenkins on Ubuntuでテストのログが文字化けする原因と解決策【Java 21対応・2025年版】

2013年8月6日

CIサーバーのJenkinsでテストを実行したら、ビルドログやJUnitレポートが文字化けしていて困っていませんか？

日本語のテスト名、エラーメッセージ、アサーションの内容が「??」や「???」に化けてしまうと、障害の原因特定に余計な時間がかかります。特に夜間ビルドで文字化けが起きていると、翌朝のレビューが苦痛になります。

この問題はJenkinsとJVMのエンコーディング設定が噛み合っていないことが根本原因で、正しい設定をすれば確実に解決できます。この記事では、Ubuntu上のJenkins（2025年版・LTS対応）でテストログが文字化けする原因を体系的に整理し、環境ごとの具体的な解決策をまとめます。

Jenkinsのコンソール出力で日本語が文字化けしている様子

この記事で解決できること

  • ✅ JenkinsのコンソールログやJUnitレポートの文字化けを修正できる
  • ✅ systemd管理のJenkins（LTS 2.332以降）での設定方法がわかる
  • ✅ Maven・Gradleビルドツールごとの設定方法がわかる
  • ✅ Ubuntu 22.04・24.04での推奨設定がわかる

動作確認環境: Ubuntu 22.04 LTS / Ubuntu 24.04 LTS / Jenkins LTS 2.479.x / Java 17・Java 21

問題の再現と確認

症状

Jenkinsのコンソール出力やJUnitレポートで、日本語部分が以下のように表示される：

テスト名：?????
エラーメッセージ：??????????????????
org.opentest4j.AssertionFailedError: ????????????????????
    at com.example.SampleTest.test??????(SampleTest.java:25)

Gradleでテストを実行すると：

# Gradle test実行例（文字化けが起きている状態）
./gradlew test

> Task :test FAILED
    ???Test > ???()??? FAILED
        org.junit.ComparisonFailure at SampleTest.java:20

現在のエンコーディング確認方法

JenkinsのWeb UIから確認できます。ブラウザで http://[jenkinsホスト]/systemInfo を開き、file.encoding の値を確認してください。UTF-8 以外（US-ASCII、ANSI_X3.4-1968 など）になっている場合、文字化けが発生します。

Jenkinsのシステム情報ページでfile.encodingを確認している様子

コマンドラインでも確認できます：

# Javaのデフォルトエンコーディングを確認
java -XshowSettings:all -version 2>&1 | grep encoding

# システムのロケール確認
locale

# Jenkinsプロセスの環境変数を確認
cat /proc/$(pgrep -f jenkins.war)/environ | tr '\0' '\n' | grep -E 'LANG|ENCODING|JAVA'

原因

なぜ文字化けが起きるか

JenkinsはJavaアプリケーションです。Javaは起動時にOSのデフォルトロケールを参照してファイルエンコーディングを決定しますが、Ubuntu Serverの最小インストール環境ではロケールが適切に設定されていないことがあります。

また、Jenkins 2.332以降はsystemdで管理されるようになったため、従来の /etc/default/jenkins への設定が効かなくなったケースも文字化けの原因になっています。

原因の種類

原因 発生条件 頻度
JVMのデフォルトエンコーディングがUTF-8以外 Ubuntu Serverの最小インストール環境 高
systemd移行後の設定ファイルの場所が変わった Jenkins LTS 2.332以降にアップグレード後 高
Maven/Gradleのテスト実行プロセスにエンコード設定がない ビルドツール側の設定漏れ 中
OSのLANG環境変数が未設定 サーバーの初期セットアップ不足 中
JNLPエージェント（スレーブ）側の設定不足 分散ビルド環境 低

解決策

解決策1: systemd override.confでJVMオプションを設定する（推奨）

Jenkins LTS 2.332以降、Ubuntuのパッケージ版JenkinsはsystemdでManageされています。この場合、設定は override.conf で行います。

# systemctl editコマンドで設定ファイルを開く（推奨）
sudo systemctl edit jenkins

エディタが開いたら以下を入力して保存します：

[Service]
Environment="JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"

または、直接ファイルを作成・編集する場合：

# ディレクトリを作成
sudo mkdir -p /etc/systemd/system/jenkins.service.d/

# override.confを作成
sudo nano /etc/systemd/system/jenkins.service.d/override.conf

ファイルの内容：

[Service]
Environment="JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"

設定を反映してJenkinsを再起動：

sudo systemctl daemon-reload
sudo systemctl restart jenkins

設定確認：

# Jenkinsが起動しているか確認
sudo systemctl status jenkins

ブラウザで http://[jenkinsホスト]/systemInfo を開き、file.encoding が UTF-8 になっていることを確認します。

注意: systemctl edit jenkins で作成したファイルは /etc/systemd/system/jenkins.service.d/override.conf に保存されます。このファイルはJenkinsのパッケージ更新時に上書きされないため、アップグレード後も設定が維持されます。

/etc/systemd/system/jenkins.service.d/override.confの設定内容を示すターミナル画面

解決策2: JAVA_TOOL_OPTIONS環境変数を設定する

systemd設定が難しい場合や、すべてのJavaプロセスに統一して設定したい場合は JAVA_TOOL_OPTIONS 環境変数を使います。

JenkinsのWeb UI（「Jenkinsの管理」→「システムの設定」→「グローバルプロパティ」）から環境変数を設定します：

変数名: JAVA_TOOL_OPTIONS
値: -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

または、/etc/environment にシステム全体の設定を追加する方法もあります：

# /etc/environmentに追記
echo 'JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"' | sudo tee -a /etc/environment

# 設定を反映してJenkinsを再起動
source /etc/environment
sudo systemctl restart jenkins

注意: JAVA_TOOL_OPTIONS はシステム上のすべてのJavaプロセスに影響します。特定のアプリケーションで問題が起きる場合は、解決策1のJenkins専用設定を使ってください。

解決策3: OSのLANG設定を修正する

JVMはOSのロケール設定を参照してデフォルトエンコーディングを決めます。OSレベルでUTF-8のロケールを設定することで根本的に解決できます。

# 現在のロケール確認
locale

# UTF-8ロケールのインストール（インストールされていない場合）
sudo apt-get install -y language-pack-ja
sudo locale-gen ja_JP.UTF-8

# または英語UTF-8でもOK
sudo locale-gen en_US.UTF-8

# デフォルトロケールを設定
sudo update-locale LANG=ja_JP.UTF-8 LC_ALL=ja_JP.UTF-8
# または
sudo update-locale LANG=en_US.UTF-8

# システムを再起動または再ログイン後に確認
locale

設定後の確認：

$ locale
LANG=ja_JP.UTF-8
LC_CTYPE="ja_JP.UTF-8"
LC_NUMERIC="ja_JP.UTF-8"
# ... 各項目がUTF-8になっていればOK

localeコマンドの出力でUTF-8が設定されている様子

解決策4: Mavenのテスト設定で明示的にエンコーディングを指定する

JenkinsサーバーのJVM設定とは別に、Mavenのテスト実行プロセス（フォークされた別プロセス）が文字化けするケースがあります。この場合は pom.xml で設定します。

<!-- pom.xml -->
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.2.5</version>
      <configuration>
        <!-- テスト実行プロセス（フォーク）にエンコーディングを指定 -->
        <argLine>-Dfile.encoding=UTF-8</argLine>
        <!-- ソースファイルのエンコーディング -->
        <encoding>UTF-8</encoding>
      </configuration>
    </plugin>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.13.0</version>
      <configuration>
        <encoding>UTF-8</encoding>
      </configuration>
    </plugin>
  </plugins>
</build>

<!-- プロジェクト全体のエンコーディング設定（推奨） -->
<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

コマンドラインから一時的に確認したい場合：

mvn test -Dfile.encoding=UTF-8

解決策5: Gradleのテスト設定でエンコーディングを指定する

Gradleでも同様に、テスト実行プロセスは別JVMで起動するため、build.gradle に設定が必要です。

// build.gradle (Groovy DSL)
test {
    useJUnitPlatform()
    // テスト実行JVMにエンコーディングを指定
    jvmArgs '-Dfile.encoding=UTF-8', '-Dsun.jnu.encoding=UTF-8'
}

// コンパイル時のエンコーディング指定
tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

Kotlin DSLの場合（build.gradle.kts）：

// build.gradle.kts (Kotlin DSL)
tasks.test {
    jvmArgs("-Dfile.encoding=UTF-8", "-Dsun.jnu.encoding=UTF-8")
    useJUnitPlatform()
}

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
}

コマンドラインから一時的に確認：

./gradlew test -Dfile.encoding=UTF-8

よくある関連エラーと対処法

JNLPエージェント（スレーブノード）で文字化けする

Jenkinsのエージェント（スレーブ）ノードで実行されるジョブが文字化けする場合、エージェント側のJVM設定が必要です。

# エージェントの起動コマンドにJVM引数を追加
java -Dfile.encoding=UTF-8 -jar agent.jar -jnlpUrl [url] -secret [secret]

Jenkinsのノード設定（「ノードの管理」→ 対象ノード→「設定」→「起動方法」）でJVM引数を設定することもできます。

ANSI_X3.4-1968 と表示されて変更できない

このエンコーディングはロケールが設定されていない環境で表示されます。

# ロケールが設定されていない場合の症状
$ java -XshowSettings:all -version 2>&1 | grep encoding
    file.encoding = ANSI_X3.4-1968

# 対処: /etc/default/localeを確認・修正
cat /etc/default/locale
# LANG=ja_JP.UTF-8 が設定されていることを確認

Java 17/21でのstdout.encodingの扱い

Java 17以降では file.encoding に加えて stdout.encoding も考慮が必要です。

# Java 17/21 でのエンコーディング確認
java -XshowSettings:all -version 2>&1 | grep -E 'encoding|charset'

必要に応じて以下のオプションを追加します：

-Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8

まとめ

Jenkins on Ubuntuでテストのログが文字化けする問題について解説しました。

  • 主な原因: JVMのデフォルトエンコーディングがUTF-8以外になっている。特にsystemd移行後（Jenkins LTS 2.332以降）は設定ファイルの場所が変わっている
  • 最短の解決策: sudo systemctl edit jenkins で /etc/systemd/system/jenkins.service.d/override.conf に -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 を追記する
  • 再発防止策: Maven/Gradleのビルドファイルにもエンコーディングを明示的に設定しておく。新しいノードを追加するときはOS・JVM・ビルドツールの3層でUTF-8設定を確認する

Ubuntu Serverのセットアップ時にLANG設定を忘れることが多いので、Jenkinsインストールの前にロケール設定を済ませる習慣を持つとトラブルを防げます。

解決できた方は、同様の問題で困っているチームメンバーにも共有してみてください。

関連記事

ubuntu

Posted by GENDOSU