◉ANTIGRAVITY LABEN
記事一覧/アプリ開発
▣ アプリ開発/2026-03-30中級

Antigravity のデプロイ・ビルドエラーを切り分けて直す実践手順

Antigravity のデプロイ・ビルドで謎のエラーに遭遇したときの切り分け手順です。TypeScript 型エラー、依存関係、環境変数、プラットフォーム固有という4つの分類で解決策を整理し、ビルドを成功させるための事前チェックリストも用意しました。

Antigravity386デプロイ5ビルドエラートラブルシューティング35

Antigravity でアプリケーションをデプロイしようとしたら、謎のエラーが表示される...。そんなトラブルに直面した経験はありませんか？ビルドやデプロイのエラーは、エラーメッセージだけでは原因が分かりにくいことも多いです。ここでよくあるエラーを エラーメッセージ別に分類 し、それぞれの原因と具体的な解決手順を詳細に説明していきます。

デプロイ・ビルドエラーの全体図

デプロイ・ビルドエラーは、大きく分けて以下の4カテゴリに分類できます：

  1. TypeScript 型エラー：コンパイル時に型の不整合が検出される
  2. 依存関係エラー：npm パッケージのインストール・互換性に関する問題
  3. 環境変数エラー：.env ファイルや本番環境の設定不備
  4. プラットフォーム固有エラー：Vercel / Netlify / Cloudflare workers など、デプロイ先固有の制限

まずは、表示されているエラーメッセージをよく読み、どのカテゴリに属するのかを特定することが大切です。

TypeScript 型エラーの解決

エラー例：「Type 'unknown' is not assignable to type...」

このエラーは、型注釈がないまま変数を使っているときに発生します。

// ❌ エラー：型が明示されていない
const response = fetch(apiUrl);
const data = response.json(); // Type 'unknown' エラー
 
// ✓ 修正：明確な型注釈
const response: Response = await fetch(apiUrl);
const data: unknown = await response.json();
if (data && typeof data === 'object') {
  const result = data as Record<string, any>;
  console.log(result.name);
}

解決手順：

  1. エラーメッセージ内の「line XX」で指定された行をコード内で確認
  2. その行の変数に対して、明確な型注釈（: Type）を追加
  3. 非同期処理の場合は await を付与
  4. 再度ビルドを試行

エラー例：「Cannot find module 'moduleName'」

このエラーは、インポートしているモジュールが見つからない場合に発生します。

// ❌ エラー：ファイルパスが誤っている
import { Component } from './components/Button';
 
// ✓ 修正：正確なパスを確認
import { Component } from './components/button'; // ファイル名は小文字
// または
import Button from './components/Button'; // デフォルトエクスポートの場合

確認項目：

  • ファイル名の大文字・小文字が一致しているか（Linux 系システムは大文字小文字を区別）
  • ファイルパスが正確か（../ の数が正しいか）
  • 該当ファイルが実際に存在するか

エラー例：「Property 'X' does not exist on type 'Y'」

このエラーは、存在しないプロパティにアクセスしているときに発生します。

// ❌ エラー：resultオブジェクトに titalプロパティはない
interface Article {
  title: string;
  content: string;
}
const article: Article = { title: 'Hello', content: 'World' };
console.log(article.tital); // Property 'tital' does not exist
 
// ✓ 修正：プロパティ名のスペルを正す
console.log(article.title);
 
// または、型定義を拡張
interface Article {
  title: string;
  content: string;
  author?: string; // オプショナルプロパティ
}

これはスペルミスと型定義の不整合の2パターンで発生します。レスポンスの型定義が古い場合は、API の最新スキーマを確認してください。

依存関係エラーの解決

エラー例：「npm ERR! ERESOLVE unable to resolve dependency tree」

複数のパッケージが互いに異なるバージョンを要求しており、npm が依存関係を解決できないときに発生します。

解決手順（推奨順）：

方法1：--legacy-peer-deps フラグを使用

npm install --legacy-peer-deps

このフラグは、npm が peer dependency の不整合を無視するよう指示します。多くの場合、これで解決します。

方法2：package-lock.json を削除してリセット

rm package-lock.json
npm install

この方法は、キャッシュされた古い依存関係情報を削除し、最新の互換性のあるバージョンを再計算します。

方法3：特定パッケージのバージョンを明示的に指定

# 例：Reactとそのプラグインのバージョンを統一
npm install react@18 react-dom@18 @types/react@18

package.json で各パッケージのバージョンを確認し、不整合があれば統一します。

エラー例：「Cannot find module 'next/config' or similar」

パッケージがインストールされていない、または不正にインストールされている場合に発生します。

# node_modules を完全削除してリセット
rm -rf node_modules
npm install
 
# または、より厳密にキャッシュもクリア
npm cache clean --force
rm -rf node_modules
npm install

特に Antigravity CLI を使用している場合、以下コマンドで推奨バージョンを確認できます：

antigravity doctor

このコマンドは、Node.js バージョン、npm バージョン、必須パッケージの有無などをチェックします。

エラー例：「ERR! code ENETUNREACH」

ネットワーク接続の問題で、npm レジストリにアクセスできないときに発生します。

# インターネット接続を確認
ping registry.npmjs.org
 
# npm レジストリのステータスを確認
npm config get registry
 
# NPM キャッシュをクリア
npm cache clean --force
 
# DNS をリセット（macOS/Linux の場合）
sudo dscacheutil -flushcache
 
# 再度インストール
npm install

環境変数エラーの解決

エラー例：「process.env.NEXT_PUBLIC_API_URL is undefined」

Next.js や他のフレームワークでは、環境変数を明示的に定義する必要があります。特に、クライアント側で使用する環境変数には NEXT_PUBLIC_ 接頭辞が必須です。

// ❌ エラー：プライベート環境変数をクライアント側で使用
const apiKey = process.env.API_KEY; // ビルド時に undefined
 
// ✓ 修正：公開環境変数として定義
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const apiKey = process.env.NEXT_PUBLIC_API_KEY;

.env.local ファイルの設定：

# クライアント側で使用
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_API_KEY=YOUR_API_KEY
 
# サーバー側のみで使用
DATABASE_URL=postgresql://user:password@localhost/dbname
SECRET_KEY=your-secret-key

本番環境での設定（Vercel の例）：

Vercel ダッシュボード → Settings → Environment Variables で、同じ環境変数を登録します。

エラー例：「Cloudflare Workers のビルド失敗」

Cloudflare Workers にデプロイする際、ファイルサイズやサポートされていない API の使用でビルド失敗することがあります。

// ❌ エラー：fs モジュールは Cloudflare Workers では使用不可
const fs = require('fs');
const file = fs.readFileSync('data.json');
 
// ✓ 修正：事前にビルド時にファイルを処理
// build.js で処理してバンドルに含める

Antigravity で Cloudflare Workers にデプロイする場合は、「Cloudflare Workers AI エッジアプリ」ガイドを参照してください。

プラットフォーム固有エラーの解決

Vercel でのビルド失敗

エラー：「Build failed」（原因が不明な場合）

  1. Vercel ダッシュボード → Deployments → [デプロイ] → Logs を確認
  2. 「ERROR」や「WARNING」で検索し、具体的なエラーメッセージを抽出
  3. 以下のチェックリストを実行
# ローカルでVercelと同じ条件でビルド
npm install
npm run build
 
# エラーが出ない場合、環境変数の不整合の可能性
# Vercelダッシュボードと .env.local を照合

Netlify でのビルド失敗

Netlify の場合、netlify.toml ファイルで明示的にビルドコマンドを指定する必要があります。

[build]
  command = "npm install --legacy-peer-deps && npm run build"
  functions = "netlify/functions"
  publish = ".next"
 
[build.environment]
  NODE_VERSION = "18"
  NPM_VERSION = "9"

よくあるエラーと対応：

エラー原因対策
"Command npm not found"Node.js / npm がインストールされていないnode_version を netlify.toml に明記
".next folder not found"ビルドフォルダの指定が誤っているpublish パスを確認
"Build timeout"ビルドに時間がかかりすぎnpm cache をクリア、依存関係を最適化

Cloudflare Workers でのビルド失敗

wrangler.toml の設定ミスでビルルエラーが発生することがあります。

# ❌ エラー：build セクションがフィールドの後にある
name = "my-worker"
main = "src/index.ts"
 
[build]
command = "npm run build"
 
# ✓ 修正：build セクションが先
[build]
command = "npm run build"
 
name = "my-worker"
main = "src/index.ts"

詳細は、「デプロイ失敗FAQ」をご参照ください。

ビルド成功のための事前チェックリスト

デプロイの前に、以下のチェックリストを実行することで、エラーの発生を大幅に減らせます：

コード品質チェック

  • [ ] TypeScript コンパイルが通るか（npm run build で確認）
  • [ ] ESLint / Prettier でコード整形エラーがないか
  • [ ] 環境変数がすべて定義されているか（.env.example との照合）
  • [ ] コンソールに警告（warning）がないか

依存関係チェック

  • [ ] npm install が成功するか
  • [ ] 新しく追加したパッケージと既存パッケージで互換性がないか
  • [ ] package.json の バージョン指定が正しいか（^1.0 vs ~1.0 vs 1.0）

環境変数チェック

# .env.local に必要な変数がすべて存在するか確認
required_vars=("NEXT_PUBLIC_API_URL" "DATABASE_URL" "SECRET_KEY")
for var in "${required_vars[@]}"; do
  if ! grep -q "^$var=" .env.local; then
    echo "Missing: $var"
  fi
done

ローカルビルドテスト

# 本番環境と同じ条件でビルド
npm run build
 
# ビルド結果を実行
npm run start
 
# ブラウザで動作確認
# http://localhost:3000

全体を振り返って

Antigravity でのビルド・デプロイエラーは、しっかりした診断プロセスで ほぼ解決できます：

  1. エラーメッセージを詳しく読む（行番号、エラーコード）
  2. エラーの種類を分類する（型エラー、依存関係、環境変数など）
  3. 対応するチェックリストを実行
  4. ローカルで再現性をテスト
  5. デプロイ先の設定を二重確認

「セットアップエラー トラブルシューティングFAQ」でも、初期セットアップ時の一般的なエラーを詳しく解説しています。

もし解決しない場合は、Antigravity サポートにエラーメッセージとログを共有してください。遠慮なくお頼りくださいね。

推奨読書

TypeScript、Node.js、デプロイメントに関するさらに詳しい知識を得たい方は、以下の書籍をお勧めします：

シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ（¥150）で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

▣ アプリ開発2026-10-15
immutable を付けた資産を同じ URL で差し替えたら、利用者のブラウザだけが古いままでした
長期キャッシュを付けた JS を同じ URL で差し替えても、CDN をパージしてもブラウザは取り直しません。同じ URL・no-cache・クエリ付き・内容ハッシュ名の 4 方式を Chromium で並べて比べ、ビルドの最後にハッシュを付ける完全なスクリプトまでをまとめました。
▣ アプリ開発2026-09-29
Cloudflare をパージしても古い壁紙が届き続けた原因は、オリジン側で JPEG を握っていた XPageSpeed
同じ URL に上書きした壁紙画像が、Cloudflare をパージしても古いまま届き続けた運用の記録です。ローカル・オリジン・エッジの三者を突き合わせて層を名指しする検査、プレフィックスパージの使いどころ、Xserver の XPageSpeed を .htaccess で安全に切る書き方まで扱います。
▣ アプリ開発2026-09-19
見積書 PDF の自動化を一度にまとめて頼み、4 つに割り直すまで
受託の見積書を毎回コピーして作っていた手作業を、Antigravity に頼んで小さな PDF 出力ツールへ移した記録です。最初に全部をまとめて頼んで作り直すことになった理由と、データ・計算・見た目・保存の 4 つに割って渡し直した順番を、動くコードと一緒に書き残します。