Thymeleafのth:srcの使い方を完全ガイド！初心者でもわかる画像やリソース設定

1. th:srcとは？

1. th:srcとは？

th:srcは、HTMLのsrc属性（画像やスクリプトの読み込み先）を サーバー側で安全に組み立てるためのThymeleaf専用属性です。見た目は通常のHTMLと同じですが、 画面を返す直前にテンプレートエンジンが実URLへ置き換えてくれるため、環境ごとのパス違いに強いのが特長です。

兄弟のth:hrefがリンク用（<a>など）なのに対し、 th:srcは主に<img>や<script>で使います。 さらに@{...}構文を使うと、アプリのコンテキストパスを自動解決してくれるため、 開発・本番のどちらでも同じ記述で動作します。

<!-- templates/index.html など -->
<img th:src="@{/images/logo.png}" alt="ロゴ">

ポイントは「HTMLに直接パスを書き固定しない」こと。th:srcに任せれば、 ルート配下や/myapp配下など配置が変わってもリンク切れを起こしにくく、 初学者でも安心して画面づくりを進められます。

2. th:srcの基本的な使い方

2. th:srcの基本的な使い方

いちばんシンプルな使い方は、画像タグのsrcをth:srcに置き換えて @{}でパスを書く方法です。@{}はアプリのコンテキストパスを自動解決するため、 開発環境でも本番環境でも同じ記述で正しいURLに展開されます。

<!-- templates/index.html など -->
<img th:src="@{/images/sample.jpg}" alt="サンプル画像">

画像は通常、src/main/resources/static/images/に置きます。 つまりファイルの実体がstatic/images/sample.jpgなら、上記1行で正しく表示されます。 HTMLに絶対パスを書かなくてよいので、配置を変えても壊れにくいのが利点です。

<!-- 素のHTML: 環境が変わるとパスずれしやすい -->
<img src="/images/logo.png" alt="ロゴ">

<!-- Thymeleaf: 環境に合わせて自動調整 -->
<img th:src="@{/images/logo.png}" alt="ロゴ">

なお、altには画像の内容を短く書いておくと、読み上げや表示失敗時にも親切です。 ここまでが「固定ファイルを表示する」ための基本です。まずは画像1枚から試して、表示されるか確認しましょう。

3. 動的なURLや変数をth:srcで指定する

3. 動的なURLや変数をth:srcで指定する

画像名やディレクトリが状況によって変わる場合は、@{...}の中で 文字列結合と変数（${...}）を組み合わせます。テンプレート側は難しく見えますが、 「先頭のパス + コントローラから受け取ったファイル名」という発想でOKです。

<!-- templates/gallery.html の一部 -->
<img th:src="@{'/images/' + ${imageName}}" alt="動的画像">

たとえばimageNameがexample.pngなら、実行時に src="/images/example.png"へ展開されます。拡張子まで含めた完全なファイル名を 渡しておくのがコツです。

@Controller
public class GalleryController {
    @GetMapping("/gallery")
    public String show(Model model) {
        model.addAttribute("imageName", "example.png"); // ← ここを切り替えるだけ
        return "gallery"; // templates/gallery.html
    }
}

<img th:src="@{'/images/' + ${folder} + '/' + ${fileBase} + '.' + ${ext}}" alt="可変画像">

うまく表示されない場合は、受け取る変数名のタイポやstatic/配下のフォルダ構成を見直しましょう。 「モデルに入れる → テンプレートで取り出す」という流れを意識すると、迷いにくくなります。

4. th:srcをCSSやJavaScriptで活用する

4. th:srcをCSSやJavaScriptで活用する

th:srcは画像だけでなく、CSSやJavaScriptファイルにも使用できます。

以下はCSSファイルを指定する例です。

<link rel="stylesheet" th:href="@{/css/style.css}">

JavaScriptファイルを指定する場合：

<script th:src="@{/js/script.js}"></script>

これにより、動的にCSSやJavaScriptのパスを指定し、管理しやすくなります。

5. th:srcの実行結果

5. th:srcの実行結果

それでは、上記のコードを実際に使用した場合の出力結果を確認しましょう。

<img src="/images/sample.jpg" alt="サンプル画像">
<script src="/js/script.js"></script>
<link rel="stylesheet" href="/css/style.css">

6. th:srcのポイント整理

6. th:srcのポイント整理

th:srcは、Thymeleafで画像やJavaScriptなどの外部ファイルを読み込むときにとても便利な仕組みです。 HTMLだけで書くとパスの指定がずれて表示されないことがありますが、th:srcを使うと アプリの動作環境に合わせて自動でパスが調整されるため、初心者でも安心して使えます。

また、画像のファイル名を変更したり、サーバー側でパスを切り替えたいときにも柔軟に対応できます。 実際のコードを見ながら、どんな場面で役立つのかイメージしてみましょう。

<!-- 画像の表示 -->
<img th:src="@{/images/logo.png}" alt="ロゴ">

<!-- JavaScriptファイルの読み込み -->
<script th:src="@{/js/menu.js}"></script>

さらに、ファイル名を動的に変更したい場合は変数と組み合わせることもできます。 たとえば、季節ごとに画像を切り替えるようなサイトでも、毎回HTMLを書き換えずに済みます。

<img th:src="@{'/images/' + ${seasonImage}}" alt="季節の画像">

最後に整理しておきましょう。

• th:srcで画像やスクリプトのパスを自動補完できる。
• 開発環境と本番環境でパスが違っても自動で調整される。
• 変数を使えばファイル名の切り替えや動的処理も簡単。

まずは1つ画像を表示するところから試してみると理解しやすく、 「HTMLのパスが通らない」という悩みから解放されます。

まとめ

まとめ

今回の記事では、Thymeleafのth:src属性について学びました。th:srcは画像やCSS、JavaScriptなどのリソースパスを動的に管理するために非常に便利な機能です。具体的な使い方や実行例を交えながら、その効果的な利用方法を理解できたと思います。

特に、@{}構文を使ったパス指定や変数を利用した動的なパス生成は、テンプレートエンジンとしてのThymeleafの強みを活かした使い方でした。また、CSSやJavaScriptの管理にも利用できる点で、効率的なフロントエンド開発が可能になります。

th:srcの基本を押さえることで、Thymeleafを使った開発がよりスムーズになります。これらの知識を実践的に活用していきましょう。

<img th:src="@{/images/logo.png}" alt="ロゴ画像">
<link rel="stylesheet" th:href="@{/css/main.css}">
<script th:src="@{/js/app.js}"></script>
    

上記のコード例を参考に、自分のプロジェクトで試してみてください。

この記事を読んだ人からの質問

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

Thymeleafのth:srcとth:hrefの違いは何ですか？

Thymeleafのth:srcは画像、JavaScriptファイル、CSSファイルなどの静的リソースのパスを指定するための属性で、HTMLのimgタグやscriptタグに使われます。一方、th:hrefはリンク先のURLを指定するための属性で、aタグやlinkタグに使用されます。どちらもThymeleafで動的なパスを生成できますが、役割が異なるため使い分けが必要です。Spring BootとThymeleafを組み合わせたWebアプリ開発では頻繁に登場し、特に静的リソースの管理ではth:srcを使うことでパスのずれによる画像やJavaScript、CSSが読み込めないトラブルを防ぐことができます。

Thymeleafのth:srcを使うとき、@{}構文は必ず必要ですか？

はい、基本的には@{}構文を使います。@{}構文はコンテキストパスを解決し、開発環境と本番環境でパスが変わっても自動的に正しいURLを生成してくれます。たとえば同じHTMLコードをローカル環境で動かす場合と本番サーバーにデプロイした場合でルートパスが違っても、th:srcで@{}を使うことでパスの修正が不要になります。Thymeleaf初心者がつまずきやすいポイントですが、@{}構文を習慣的に使うと安心です。

Thymeleafで画像パスが読み込まれないときに確認すべきことは何ですか？

Thymeleafでth:srcを使ったのに画像が読み込まれない場合、まず画像ファイルの配置場所を確認してください。Spring Bootではstaticディレクトリ配下に配置する必要があります。次に、パスのタイプが間違っているケースもあります。相対パスと絶対パスが混在すると正しく表示されない場合があります。また@{}構文を入れ忘れるとパスが解決されず404エラーになることもあります。さらにブラウザのキャッシュが古いデータを保持している場合もあるので、キャッシュ削除も効果的です。