mcpField
N
netlify-cli-and-deploy

netlify-cli-and-deploy

github.com/netlifyクラウド・DevOps471.0k 回インストール6 日前に更新
リポジトリ

netlify-cli-and-deploy について

netlify-cli-and-deployは、Netlify CLIとデプロイ手順を扱うガイドです。ローカル、CI、Git経由でサイトを開発・公開するチーム向けに、サイト連携、各種デプロイ、ローカル開発、環境変数管理を説明します。

主な機能

  1. 01Netlifyサイトのリンク
  2. 02プレビューと本番デプロイの実行
  3. 03Git継続デプロイの設定
  4. 04ローカル開発サーバーの利用
  5. 05デプロイコンテキスト別の環境変数管理

活用シーン

  1. 01ローカルでビルドしてサイトを手動デプロイ
  2. 02CIから対象サイトへ公開
  3. 03プルリクエスト用のデプロイプレビュー作成
  4. 04Functionsやリダイレクトのローカルテスト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/netlify/context-and-tools --skill netlify-cli-and-deploy

インストール後、Claude Code で/netlify-cli-and-deployを入力して読み込まれたか確認します。

詳細

Netlify CLI とデプロイ

インストール

npm install -g netlify-cli    # Global (for local dev)
npm install netlify-cli -D    # Local (for CI)

Node.js 18.14.0 以降が必要です。

認証

netlify login       # Opens browser for OAuth
netlify status      # Check auth + linked site status

CI では、代わりに環境変数 NETLIFY_AUTH_TOKEN を設定してください。

CI では、デプロイ先のサイトも指定する必要があります。 NETLIFY_AUTH_TOKEN は認証のみを行い、デプロイ先のサイトを選択するものではありません。CI にはリンク済みの .netlify/state.json がないため、netlify deploy が公開先を認識できるよう、サイトの API／プロジェクト ID（サイトの設定画面に Project ID として表示）を NETLIFY_SITE_ID として環境変数に設定してください。これを設定しない場合、CI のデプロイ先サイトが特定されず、失敗するか入力を求められます。ローカルでは netlify link がサイト ID を .netlify/state.json に書き込むため、この問題は発生しません。CI にはそのようなファイルがありません。

サイトのリンク

netlify status でリンク済みかどうかを確認します。まだリンクされていない場合：

# Interactive
netlify link

# By Git remote (if using Git)
netlify link --git-remote-url https://github.com/org/repo

# Create new site
netlify init           # With Git CI/CD setup
netlify init --manual  # Without Git CI/CD

サイト ID は .netlify/state.json に保存されます。.netlify を .gitignore に追加してください。

デプロイ

Git ベースのデプロイ（継続的デプロイ）

netlify init でセットアップします。プッシュや PR をきっかけに自動デプロイが実行されます：

  • 本番ブランチにプッシュ → 本番デプロイ
  • PR を作成 → 固有の URL を持つデプロイプレビュー
  • その他のブランチにプッシュ → ブランチデプロイ。ただし、ブランチデプロイが有効な場合のみです。デフォルトでは無効のため、サイトのビルドとデプロイの設定で（ブランチごと、またはすべてのブランチに対して）有効にしてください

ビルドは Netlify のサーバーで実行されます。ビルド設定は netlify.toml で構成してください。

netlify.toml は UI の設定より優先されます。 netlify.toml のファイルベースの設定は、Netlify の UI で構成した同等のビルド設定より優先されます。同じオプションを両方で設定した場合、コミット済みの netlify.toml が優先されます。ファイルを変更して再デプロイするまで、ダッシュボードでその設定を編集しても反映されません。UI でビルドコマンド、公開ディレクトリ、ベースディレクトリを変更したのに、コミット済みの古い値がデプロイのたびに適用され続けるため、戸惑うことがあります。

モノレポでの設定ファイルの検索順序。 モノレポでは、Netlify は次の順序で netlify.toml を検索し、最初に見つかったものを使用します：(1) パッケージディレクトリ、(2) ベースディレクトリ、(3) リポジトリのルート。サイト固有の netlify.toml は、パッケージディレクトリ（そのサイトを含むサブディレクトリ）に配置し、ルートレベルの設定より優先されるようにしてください。ルートレベルの netlify.toml で設定したベースディレクトリも、UI で構成したベースディレクトリより優先されます。

手動／ローカルデプロイ（Git 不要）

ローカルでビルドしてからアップロードします：

netlify deploy          # Draft deploy (preview URL)
netlify deploy --prod   # Production deploy
netlify deploy --dir=dist  # Specify output directory

Git を使わずに実行できます。プロトタイプ、ローカルのみのプロジェクト、CI パイプラインに便利です。

手動の --prod デプロイは、次の Git プッシュで置き換えられます。 同じサイトで Git の継続的デプロイも接続されている場合、本番ブランチへの次のプッシュで新しいビルドが実行され、自動公開されて、手動で公開した --prod デプロイが置き換えられます。手動で公開したビルドは、何も通知されずに本番環境から消えます。特定のデプロイを公開状態に保つには、UI のサイトの「デプロイ」一覧から公開済みデプロイをロック（「自動公開を停止」）してください。ロック中も新しいプッシュでビルドは実行されますが、ロックを解除するか手動で公開するまで自動公開されません。同じ本番ブランチで手動の --prod デプロイと Git CD を併用すると、次のコミットが勝つ競争状態になります。

デプロイ URL はリンクを知っている人なら誰でもアクセスできます

ドラフトデプロイ（netlify deploy）、デプロイプレビュー、ブランチデプロイ、デプロイのパーマリンクにはそれぞれ、リンクを知っている人なら誰でも開ける固有の URL が割り当てられます。URL が推測しにくく、一覧に表示されないからといって、非公開になるわけではありません。そのため、プレビュー URL を機密情報や未公開コンテンツの安全な場所として扱わないでください。アクセスを実際に制限するには、UI でサイト保護（パスワード保護、またはチーム／SSO 保護）を有効にしてください。すべてのデプロイを保護することも、本番以外のデプロイのみを保護することもできます。

ローカル開発

オプション 1：netlify dev
netlify dev

フレームワークの開発サーバーをラップし、次の機能を提供します：

  • 環境変数の挿入
  • Functions とエッジ関数
  • リダイレクトとヘッダーの処理
オプション 2：Netlify Vite Plugin（Vite ベースのプロジェクト）

Vite を使用するプロジェクト（React SPA、TanStack Start、SvelteKit、Remix）では、Vite プラグインにより、フレームワークの開発サーバーで Netlify プラットフォームのプリミティブを直接利用できます。

npm install @netlify/vite-plugin

// vite.config.ts
import netlify from "@netlify/vite-plugin";
export default defineConfig({ plugins: [netlify()] });

その後、通常の開発コマンド（npm run dev）を実行します。netlify dev でラップする必要はありません。これにより、開発中に Blobs、DB、Functions、環境変数を利用できます。

フレームワークごとのローカル開発ガイダンスについては、netlify-frameworks スキルをご覧ください。

環境変数

CLI での管理
# Set
netlify env:set API_KEY "value"
netlify env:set API_KEY "value" --secret              # Hidden from logs
netlify env:set API_KEY "value" --context production   # Context-specific

# Get
netlify env:get API_KEY

# List
netlify env:list
netlify env:list --plain > .env                        # Export to file

# Import from file
netlify env:import .env

# Delete
netlify env:unset API_KEY
コンテキストのスコープ設定

変数はデプロイコンテキストごとにスコープを設定できます。

netlify env:set API_URL "https://api.prod.com" --context production
netlify env:set API_URL "https://api.staging.com" --context deploy-preview
netlify env:set DEBUG "true" --context branch:feature-x
コードでのアクセス
  • サーバー側（Functions）：Netlify.env.get("VAR")（推奨）または process.env.VAR を使用します。
  • クライアント側（Vite）：import.meta.env.VITE_VAR を使い、VITE_ が付いた変数のみ使用できます。
  • クライアント側（Astro）：import.meta.env.PUBLIC_VAR を使い、PUBLIC_ が付いた変数のみ使用できます。

シークレットに VITE_ または PUBLIC_ の接頭辞を使用しないでください。これらはブラウザーに公開されます。

コマンドが失敗したら、ユーザーに伝えて停止する

netlify コマンド、デプロイ、または netlify dev が失敗した場合は、正確なエラー、デプロイログの URL（CLI に表示されます）、影響を受けたサイト／ブランチを添えて、失敗をユーザーに報告し、停止してください。復旧コマンドを考案したり、より低レベルのツールにエスカレーションしたりしないでください。https://api.netlify.com/... に対して curl を実行したり、復旧手段として netlify api <method> を実行したり、操作を強行するためにディスク上の認証トークンを読み取ったりしてはいけません。ドキュメントに記載された通常の手順が機能しない場合、それはユーザーに把握してもらうべきプラットフォームの状態に関する問題です。

便利なコマンド

コマンド説明
netlify status認証とサイトのリンク状態を確認します
netlify devローカル開発サーバーを起動します
netlify buildローカルでビルドを実行します（Netlify 環境を再現します）
netlify deployドラフトデプロイを実行します
netlify deploy --prod本番デプロイを実行します
netlify dev:exec <cmd>Netlify 環境を読み込んでコマンドを実行します
netlify env:list環境変数を一覧表示します
netlify clone org/repoクローン、リンク、セットアップを一度に行います

コメント

Markdown 対応