PostCSS で @import が展開されず 1 ファイルにまとまらない

要約

PostCSS は標準では @import を展開しない。
CSS の @import はブラウザが実行時に解決する仕様なので、ビルド時に 1 ファイルへまとめたい場合は postcss-import を入れる。

そして、このプラグインは配列の先頭に置く必要がある。

// postcss.config.js
export default {
  plugins: {
    "postcss-import": {},
    autoprefixer: {},
  },
};

実行例

postcss-import を入れない設定では @import が展開されずそのまま出力に残り、プラグインの先頭に置くと reset.css の中身が取り込まれて Autoprefixer のプレフィックスも付く。@import を body のルールより後ろに書くと取り込まれず、警告が出る。

$ npx postcss src/app.css
@import "./reset.css";
 
body {
  margin: 0;
}

$ npx postcss src/app.css
.reset-box {
  -webkit-user-select: none;
          user-select: none;
}
body {
  margin: 0;
}

$ npx postcss src/app.css
body {
  margin: 0;
}
 
5:1	⚠  @import statements must precede all other statements (besides @charset or empty @layer) and be consecutive [postcss-import]

— 2026-10-22 時点の出力

解決策

1. postcss-import を先頭に置く

導入して、配列の先頭に置く。

npm install -D postcss-import

// postcss.config.js
export default {
  plugins: {
    "postcss-import": {},
    "postcss-nesting": {},
    autoprefixer: {},
  },
};

配列記法の場合も順序の考え方は同じだ。

import postcssImport from "postcss-import";
import autoprefixer from "autoprefixer";
 
export default {
  plugins: [postcssImport(), autoprefixer()],
};

2. @import をファイルの先頭にまとめる

有効な位置に書かれているかを確認する。

/* src/app.css */
@import "./reset.css";
@import "./tokens.css";
 
:root {
  --color-bg: #0b0b0c;
}

次のように途中へ書いたものは、ブラウザでも展開されない。

body {
  margin: 0;
}
 
@import "./reset.css"; /* ここでは無効 */

3. パッケージの読み込み方を確認する

node_modules 配下のパッケージは、パッケージ名だけで書ける。
公式リポジトリの説明では、モジュールを読み込むとき index.css か package.json の style / main フィールドが指すファイルを探す。

@import "normalize.css";

~ を付ける記法は webpack の css-loader 側の慣習で、postcss-import では不要だ。

4. 出力を見て確かめる

ビルド後の CSS に @import が残っていれば、展開されていない。

npx postcss src/app.css -o dist/app.css
grep -n "@import" dist/app.css

何も出なければ展開できている。
ただし @import を他のルールより後ろに書いた場合は、postcss-import が @import statements must precede all other statements という警告を出して取り込まず、その行も出力から消えるので grep では何も出ない。
ビルド時の警告も合わせて確認する。
設定ファイル自体が読み込まれていない可能性もあるので、そのときは /postcss/config-not-loaded-esm/ を確認する。

よくある原因

1. プラグインが入っていない: PostCSS 本体は CSS を解析して変換する土台であり、@import の解決は担当しない。
   出力にも @import がそのまま残る。
2. 配列の途中に置いている: 公式リポジトリは「This plugin should probably be used as the first plugin of your list. This way, other plugins will work on the AST as if there were only a single file to process」と書いている。
   後ろに置くと、それより前のプラグインは読み込み先の CSS を見ないまま処理を終える。
   Autoprefixer をこの順序で外すと、読み込んだファイルにだけプレフィックスが付かない状態になる。
3. @import の位置が後ろすぎる: CSS の仕様上、@import は @charset と @layer を除くすべてのルールより前に書く必要がある。
   他のルールの後ろに置いた @import は無効になる。
4. パスが解決できていない: 相対パスの誤りや、パッケージ側の style / main フィールドの指す先が無い場合に、その記述だけが展開されずに残る。