WordPressのパスを理解する｜絶対パス・相対パスとCSSのurl()を解説

最初に知りたい3種類のパス

Web制作で「パス」と呼んでいるものは、ブラウザが画像やCSSなどへアクセスするためのURLまたはURLの一部です。まず、絶対URL、ルート相対URL、相対URLの違いを整理します。

絶対URLはhttpsからすべて書く

絶対URLは、通信方法、ドメイン、ファイルまでを省略せずに書く方法です。別のページや別サイトから見ても、参照先は変わりません。

<img src="https://example.com/wp-content/themes/my-theme/assets/images/photo.jpg" alt="サンプル画像">

ルート相対URLは先頭をスラッシュにする

先頭が/のURLは、ドメイン直下を基準にします。短く書けますが、WordPressをサブディレクトリへ設置している場合や、テーマ名を変更した場合に合わなくなることがあります。

<img src="/wp-content/themes/my-theme/assets/images/photo.jpg" alt="サンプル画像">

相対URLは現在地から移動する

./は同じ階層、../は一つ上の階層を表します。大切なのは、相対URLは必ず「どこを基準にするか」で結果が変わることです。

./images/photo.jpg     同じ階層にあるimagesへ進む
../images/photo.jpg    一つ上の階層へ戻ってimagesへ進む

静的サイトで相対パスの基準を確認する

同じフォルダ構成を使い、HTMLと外部CSSで基準がどのように変わるかを確認します。ここを理解すると、WordPressで画像が見つからない理由も分かりやすくなります。

static-site/
├── index.html
├── css/
│   └── style.css
└── images/
    └── photo.jpg

HTMLのsrcは表示中のページURLが基準になる

index.htmlとimagesが同じ階層にあるため、HTMLでは次のように指定できます。ブラウザは、表示しているindex.htmlのURLを基準に画像を探します。

<img src="images/photo.jpg" alt="サンプル画像">

外部CSSのurl()はCSSファイルが基準になる

style.cssはcssフォルダ内にあります。そのため、一つ上へ戻ってからimagesへ進みます。外部CSSの相対URLはCSSファイルの場所が基準です。

.hero {
  background-image: url("../images/photo.jpg");
}

インラインCSSはページURLを基準にする

HTML内の<style>やstyle属性へ書いた相対URLは、外部CSSファイルではなく、そのHTMLページのURLが基準です。同じCSSでも書く場所によって基準が変わる点に注意してください。

WordPressのPHPテンプレートで相対パスがずれる理由

WordPressでは、テーマ内のPHPファイルがHTMLを作り、ブラウザへ送ります。ブラウザからPHPファイルの保存場所は見えないため、テーマフォルダ内の位置を基準にsrcを解決することはできません。

wp-content/themes/my-theme/
├── front-page.php
└── assets/
    ├── css/
    │   └── style.css
    └── images/
        └── photo.jpg

ブラウザはPHPファイルの位置を見ていない

たとえば表示中のページがhttps://example.com/about/のとき、次のHTMLを出力すると、ブラウザはhttps://example.com/about/assets/images/photo.jpgを探します。PHPテンプレートの場所ではなく、表示中のページURLが出発地点になるためです。

<img src="assets/images/photo.jpg" alt="サンプル画像">

get_theme_file_uri()でテーマ画像のURLを取得する

テーマ内の画像をHTMLへ出力するときは、WordPressが用意しているURL取得関数を使います。通常は、子テーマの上書きにも対応できるget_theme_file_uri()を基本にすると分かりやすいです。

<img
  src="<?php echo esc_url( get_theme_file_uri( 'assets/images/photo.jpg' ) ); ?>"
  alt="サンプル画像"
>

このコードは、テーマ内の対象ファイルを探し、ブラウザで使えるURLを返します。URLをHTML属性へ出力するときはesc_url()でエスケープします。

URLとサーバー内のファイルパスを分ける

<img src>やリンクにはURLが必要です。一方、PHPのrequireやfile_get_contents()でファイルを読む場合は、サーバー内のファイルパスが必要です。URIを返す関数とファイルパスを返す関数は用途が異なります。

// ブラウザへ出力するURL
$image_url = get_theme_file_uri( 'assets/images/photo.jpg' );

// PHPがサーバー内で読むファイルパス
$data_file = get_theme_file_path( 'assets/data/sample.json' );

WordPressでもCSSのurl()は同じ考え方

WordPressだからCSSの相対URLが特別になるわけではありません。外部CSSがテーマ内のassets/css/style.cssとして読み込まれているなら、そのCSSファイルから画像までの位置を書きます。

CSSファイルから画像までの相対URLを書く

style.cssから一つ上のassetsへ戻り、imagesへ進むため、指定は../images/photo.jpgになります。

.hero {
  background-image: url("../images/photo.jpg");
}

学習するときは「url()に画像までの相対パスを書けば、外部CSSファイルの場所を基準に必要なURLが決まり、画像が表示される」と覚えておけば大丈夫です。

url()がテーマのルートを作るわけではない

url()は画像やフォントなどの参照先を書くCSS関数です。テーマ名やwp-contentを自動で調べるWordPress関数ではありません。ブラウザが、読み込んだCSSファイルのURLと../images/photo.jpgを組み合わせて参照先を判断します。

CSSファイルを移動したら相対URLも見直す

基準になるCSSファイルを別フォルダへ移動すると、画像との位置関係も変わります。CSSを整理・ビルドした後に背景画像だけ表示されない場合は、完成したCSSファイルのURLを確認してください。

テーマURL関数の使い分け

WordPressには似た名前の関数が複数あります。親テーマだけか、子テーマも含むのか、特定ファイルを探したいのかで使い分けます。

通常はget_theme_file_uri()を使う

get_theme_file_uri( 'assets/images/photo.jpg' )は、子テーマがある場合は子テーマ内のファイルを先に確認し、見つからなければ親テーマを使います。テーマファイルを子テーマで差し替えられる構成に向いています。

親テーマと子テーマを明確に指定する

テーマフォルダを直接書かない

/wp-content/themes/my-theme/を直接書くと、WordPressの設置場所、テーマ名、子テーマ構成が変わったときに修正が必要です。テーマ内の画像やスクリプトは、用途に合うWordPress関数からURLを取得してください。

公式仕様は、get_theme_file_uri()、get_stylesheet_directory_uri()、get_template_directory_uri()のコードリファレンスでも確認できます。