Next.js + Docker + microCMS で Server Error と Runtime Error が出た話

体験談

Next.js で microCMS から記事を取得しようとしたとき、2種類のエラーに遭遇しました。

1. Server Error

Server Error
Error: parameter is required (check serviceDomain and apiKey)

2. Runtime Error

Unhandled Runtime Error
Error: parameter is required (check serviceDomain and apiKey)

どちらも「microCMS の client に serviceDomain または apiKey が渡っていない」という内容ですが、原因と出るタイミングが違いました。

1. 原因と解決法

①Server Error の場合

• 発生タイミング：ビルド時（next build や getStaticProps 実行時）

  • 原因：

    • サーバー側で process.env が undefined
    • Docker の env_file 設定漏れ
    • .env.local の typo

  • 対策：

    • Docker の env_file を確認
    • コンテナを再ビルド (docker compose up -d --build)
    • .env.local の値を確認

② Runtime Error の場合

• 発生タイミング：ページを開いたとき（ブラウザで実行）
  • 原因：
    • サーバー専用の process.env をブラウザ側で読もうとした
    • createClient をモジュールトップレベルで作成していたため、client がブラウザバンドルに含まれてしまいprocess.env.SERVICE_DOMAIN が undefined になった
  • 対策：
    • createClient は getStaticProps や getServerSideProps 内で作る

修正前（NGコード）

import { createClient } from 'microcms-js-sdk';

// ここで client をトップレベルで作成していた
export const client = createClient({
  serviceDomain: process.env.SERVICE_DOMAIN,
  apiKey: process.env.API_KEY,
});

export const getPostBySlug = async (slug) => {
  const post = await client.get({
    endpoint: 'blogs',
    queries: { filters: `slug[equals]${slug}` },
  });

  return post.contents[0];
};

Unhandled Runtime Error
Error: parameter is required (check serviceDomain and apiKey)

修正版（OKコード）

import { createClient } from 'microcms-js-sdk';

export const getPostBySlug = async (slug) => {
  // サーバーサイドで client を作成
  const client = createClient({
    serviceDomain: process.env.SERVICE_DOMAIN,
    apiKey: process.env.API_KEY,
  });

  const post = await client.get({
    endpoint: 'blogs',
    queries: { filters: `slug[equals]'${slug}'` },
  });

  return post.contents[0];
};

• 対策：
  - createClient は getStaticProps や getServerSideProps 内で作る

これでブラウザに client がバンドルされず、Runtime Errorを回避することができる。

※補足　「client がバンドルされる」とは？

バンドルとは？

Next.js では、開発者が書いた複数のファイル（モジュール）をまとめて1つの JavaScript ファイル群に変換してブラウザに送ります。
この「まとめる作業」のことをバンドルと呼びます。

問題のポイント

ファイルのトップレベル（関数の外）に書いた処理は、Next.js が「これはブラウザでも必要だ」と判断して、そのままブラウザに送られる JavaScript に含めてしまうことがあります。

すると本来サーバー専用で使うはずのprocess.envやcreateClientまでブラウザに届いてしまい、undefinedになってエラーが起きてしまう。

2. Server Error と Runtime Error の違い

エラー	発生タイミング	原因	対策
Server Error	ビルド時 / サーバー実行時	サーバー側で環境変数が undefined	Docker の env_file を確認、再ビルド
Runtime Error	ページ表示時（ブラウザ実行時）	サーバー専用処理をブラウザで読み込んでいる	createClient をサーバー関数内で作る

• Server Error は「そもそも環境変数が存在しない」場合
• Runtime Error は「環境変数はあるけどブラウザ側で読もうとしている」場合

3. まとめ

• Next.js で microCMS を使うときは トップレベルで client を作らず、サーバーサイドで作る
• Docker では env_file の設定と再ビルドを忘れずに