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

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

Antigravity でデプロイやビルドが失敗する原因をエラーメッセージ別に解説し、具体的な解決手順を提供します。

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

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-07-14
デプロイは成功なのに、ユーザーには古いビルドが出ていたとき — 出荷したコミットがエッジに届いたかを検証するゲートの運用メモ
デプロイが成功と表示されたのに本番が古いビルドを配り続けていたとき、出荷したコミットが実際にエッジへ届いたかをビルド印で検証するゲートの作り方を、運用ログの実測とともに整理します。
▣ アプリ開発2026-07-15
エージェントが足した依存を、インストール前に検疫する — postinstall を既定で止めて通す設計
エージェントに任せた作業で依存が増えるとき、インストールの瞬間に走るライフサイクルスクリプトは誰も見ていません。既定を止め、検疫スコアで通す実装と運用をまとめます。
▣ アプリ開発2026-07-14
AdMob を載せた画面のスクリーンショットテストを、広告の非決定性から守る
広告つきの画面はスクリーンショットテストが毎回赤くなり、やがて誰も差分を見なくなります。AdMob バナーの非決定性を封じ、レイアウトの崩れだけを検知に残す設計を、Compose の実装例と Antigravity での差分トリアージまで含めてまとめます。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます
もっと見る →