netlify-config

Netlify の設定

設定はリポジトリのルート（またはモノレポのベース／パッケージディレクトリ）にある 3 つのファイルに記述します。

• netlify.toml — ビルド、コンテキスト、プラグイン、関数、リダイレクト、ヘッダー、開発。
• _redirects — プレーンテキストのリダイレクト／リライト規則。拡張子は付けず、公開ディレクトリに保存します。
• _headers — プレーンテキストのレスポンスヘッダー。公開ディレクトリに保存します。

値が競合する場合、netlify.toml の値がNetlify UI より優先されます。netlify.toml のパスは、ベースディレクトリ（デフォルトではルート /）を基準とした絶対パスです。

使用するモダン構文とレガシー構文

• 関数のバンドラー：node_bundler = "esbuild" を使用します。zisi はレガシーの JS デフォルトです。TypeScript では常に esbuild が使用されます。
• 一時的なリダイレクト：status = 302 を使用します。307 はサポートされていません。
• Gatsby Image CDN：非推奨の GATSBY_CLOUD_IMAGE_CDN ではなく、NETLIFY_IMAGE_CDN を使用します。
• TOML への環境変数の埋め込み：key = "$VAR" はサポートされていません（プロキシリダイレクトの signed を除く）。ビルドコマンドでの sed 置換またはビルドプラグインを使用します（下記参照）。

netlify.toml のビルドとコンテキスト

[build]
  base = "frontend"
  publish = "dist"
  command = "npm run build"
  environment = { NODE_VERSION = "18" }

[context.production]
  publish = "output/"
  command = "make publish"

[context.deploy-preview]
  publish = "dist/"

[context."feat/branch"]        # quote names with special characters
  command = "npm run preview"

[build] は Bash で実行されます。コンテキストに対応するキーには [build] と [[plugins]] が含まれますが、[[redirects]] と [[headers]] は含まれません（これらは常にグローバルです）。優先順位（低い順）：UI < toml < 任意のコンテキストプロパティ < [context.<name>] < [context.branchname]。

リダイレクトとリライト

_redirects の規則が先に処理され、その後に netlify.toml が処理されます。それぞれのファイル内では、上から下へ最初に一致した規則が適用されます。具体的な規則を一般的な規則より先に記述してください。エッジ関数はリダイレクトより前に実行されます。

SPA の履歴 pushState フォールバック（クリーン URL に必要）：

/*  /index.html  200

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

_redirects の構文 — from to [status] [conditions]、# コメント、パスは大文字と小文字を区別し、特殊文字は URL エンコードします。

/home         /              301
/my-redirect  /              302
/ecommerce    /store-closed  404          # custom 404 for a path
/pass-through /index.html    200          # rewrite
/best-pets/dogs /best-pets/cats.html 200! # force/shadow (! or force=true)
/news/*  /blog/:splat                     # splat
/news/:month/:date/:year/:slug  /blog/:year/:month/:date/:slug   # placeholders
/store id=:id  /blog/:id  301             # query params
/  /anz  302  Country=au,nz               # no spaces in value list
/israel/*  /israel/he/:splat  302  Language=he
/* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie

[[redirects]] のキーワード：from、to、status（デフォルトは 301）、force（デフォルトは false。!／シャドウ）、query（query = {path = ":path"}）、conditions（{Language, Country, Role, Cookie}）、headers（プロキシリクエストのヘッダー）、signed（署名付きプロキシの環境変数名）。

注意事項：

• リダイレクトで末尾のスラッシュを追加または削除することはできません。CDN が先に URL を正規化するため、/x/ → /x 301! の規則は無限ループになります。Pretty URLs（デフォルトで有効）を利用してください。
• スプラットのアスタリスクが使えるのはセグメントの末尾のみ（/jobs/*）であり、パスの途中（/jobs/*.html は無効）では使えません。プレースホルダー（:x）を置けるのはセグメントの先頭のみです。1 つのセグメント内でワイルドカードとプレースホルダーを組み合わせることはできません。
• スプラットからパスを除外することはできません。より具体的な規則を先に記述してください。
• Country は ISO 3166-1 alpha-2 です。言語リダイレクトで照合されるのは、Accept-Language の最初の項目のみです。
• 外部認証プロバイダーを使用するロールベースのリダイレクトは、Enterprise のみで利用できます。
• リダイレクトが 10,000 件を超える場合は、ワイルドカード／プレースホルダーまたはエッジ関数を使用してください。シリアライズされた出力が大きすぎると、デプロイに失敗します。

プロキシ

/api/*           https://api.example.com/:splat        200
/netlify-site/*  https://my-other-site.netlify.app/:splat  200   # use .netlify.app, not custom domain

[[redirects]]                     # custom request headers + force
  from = "/search"
  to = "https://api.mysearch.com"
  status = 200
  force = true
  headers = {X-From = "Netlify"}

署名付きプロキシ（signed は Runtime にスコープされた環境変数を指定します。netlify.toml に記述する必要があります。JWS は外部との通信のみで使用でき、Netlify 間では使用できません）：

[[redirects]]
  from = "/search"
  to = "https://api.mysearch.com"
  status = 200
  force = true
  signed = "API_SIGNATURE_TOKEN_PLACEHOLDER"

注意事項： チームをまたぐリライトは許可されません。同じパスワードで保護されたサイト間のリライトは可能ですが、別々に保護されたサイト間ではできません。プロキシのタイムアウトは 26 秒です。デフォルトでは 1 ホップです。相対パスのアセットは機能しません（絶対パスまたは <base> を使用してください）。ループは警告なしで無視されます。

カスタムヘッダー

/*
  X-Frame-Options: DENY
/templates/index2.html
  X-Frame-Options: SAMEORIGIN

複数の値を指定する場合は、キー（_headers）を繰り返すか、複数行の TOML 文字列を使用します。

[[headers]]
  for = "/*"
  [headers.values]
  cache-control = '''
  max-age=0,
  no-cache,
  no-store,
  must-revalidate'''

注意点：

• _headers／netlify.toml のヘッダーはグローバルで、ブランチやコンテキストには適用範囲が限定されません。回避策として、グローバルヘッダーを削除し、ヘッダーファイルをカスタムディレクトリに置いて、コンテキストごとのビルドコマンドから cp で公開ディレクトリにコピーします。

  [context.staging]
    command = "npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers"
  

• ヘッダーが適用されるのは Netlify のストアにあるファイルのみです。プロキシ経由のコンテンツや、Function／Edge（SSR）のレスポンスには適用されないため、それらには個別にヘッダーを設定する必要があります。
• Content-Length、Content-Encoding、Location（リダイレクトを使用）、Set-Cookie、Server などの名前は無視されます（サーバー側で設定）。
• Basic 認証ヘッダーは Pro／Enterprise のみです。サブドメインをまたぐ Cookie にはカスタムドメインが必要です（netlify.app は Public Suffix List に登録されています）。

Functions

[functions]
  directory = "myfunctions/"          # default: <base>/netlify/functions
  node_bundler = "esbuild"
  external_node_modules = ["package-1"]  # esbuild only; native add-ons etc.
  included_files = ["files/*.md"]        # ! prefix excludes

[functions."api_*"]                    # glob/named blocks concatenate with top-level
  external_node_modules = ["package-2"]
  included_files = ["!files/post-1.md"]

環境変数

保存方法は 2 種類あります。

• UI／CLI／API — Netlify に保存されます（リポジトリには保存されません）。サイト変数と共有変数、コンテキストごとの値、スコープに対応しています。ビルド、Function／Edge／ODB、スニペットの挿入、フォーム、署名付きプロキシで利用できます。機密情報を扱う場合はこちらを推奨します。
• netlify.toml — リポジトリに保存されます。サイト変数のみで、コンテキストごとの値には対応していますが、スコープは選択できません（すべてに Builds と Post processing が設定されます）。ビルドとスニペットの挿入でのみ利用できます。

netlify.toml の環境変数は、同じキーを持つ UI／CLI／API の変数を上書きします。

TOML でコンテキストごとの値を設定する場合：

[context.production]
  environment = { NODE_VERSION = "14.15.3" }
[context.deploy-preview.environment]
  NOT_PRIVATE_ITEM = "not so secret"
[context.branch-deploy.environment]
  NODE_ENV = "development"

CLI：

netlify env:set KEY value          # --secret marks it a secret
netlify env:import .env             # site vars; --replace-existing wipes others first
netlify env:unset KEY
netlify env:list --plain --context production > .env
netlify build                       # local build with Netlify's env vars

API：createEnvVars／updateEnvVar（is_secret: true）／setEnvVarValue／deleteEnvVar／deleteEnvVarValue。

アクセス構文： build.command／ignore.command では Bash の $VAR、Node スクリプトとプラグインでは process.env.VAR を使用します。

スコープ（Pro／Enterprise。デフォルトはすべて）：Builds（サイトのビルド）・Functions（Functions／Edge／ODB）・Runtime（フォーム、署名付きプロキシ）・Post processing（スニペットの挿入）。共有変数は Pro／Enterprise で利用でき、読み取り／編集はチームオーナーのみ可能です。サイト変数と共有変数でキーが重複する場合の優先順位はスコープごとに決まります。サイト変数が優先されるのは、その変数が設定されているスコープ内に限られます。

命名規則／上限： キーには英数字とアンダースコアを使用でき、先頭は英字にする必要があります（1KEY、_KEY1 は無効）。キーは 255 文字以下、値は 5,000 文字以下です。読み取り専用の変数名は予約されています。変更を反映するにはビルドとデプロイが必要です。

予約済みの設定変数でビルド言語を設定します — NODE_VERSION、NPM_FLAGS、YARN_VERSION、BUN_VERSION、RUBY_VERSION、PHP_VERSION、PYTHON_VERSION、GO_VERSION、HUGO_VERSION、PNPM_FLAGS、NPM_TOKEN（Yarn の場合は YARN_NPM_AUTH_TOKEN）など。

UI／CLI／API で設定する必要があります。netlify.toml には設定できません（リポジトリのクローン後に読み込まれる変数、またはランタイムのみで使う変数）：AWS_LAMBDA_JS_RUNTIME、GIT_LFS_ENABLED、GIT_LFS_FETCH_INCLUDE、NETLIFY_BUILD_DEBUG。

CI に関する注意点： デフォルトは true です。ビルドに支障が出る場合は、ビルドコマンドの先頭に CI='' を追加します。

ヘッダー／リダイレクトへの環境変数の値の挿入

key = "$VAR" はサポートされていません。使用できるのは path のみです（スコープに Builds を含める必要があります）。

[build]
  command = "sed -i \"s|HEADER_PLACEHOLDER|${PROD_API_LOCATION}|g\" netlify.toml && yarn build"

sed による置換が機能するのは [[headers]]／[[redirects]] のみです（ビルド後に読み込まれます）。ビルドコマンドより前に実行されるため、ビルドプラグインからは参照できません。プラグインから参照できるように変更するには、netlifyConfig を編集するローカルのビルドプラグインを使用します。

読み取り専用の便利なビルド変数

CONTEXT（production／deploy-preview／branch-deploy／dev）、BRANCH、COMMIT_REF、CACHED_COMMIT_REF、PULL_REQUEST、REVIEW_ID、URL、DEPLOY_URL、DEPLOY_PRIME_URL、SITE_ID、SITE_NAME。

Secrets Controller

変数をシークレットとして指定します：Contains secret values（UI）／--secret（CLI）／is_secret: true（API）。次のポリシーが強制され、カスタマイズできません。

• シークレット値は書き込み専用です。設定後に読み取り可能な状態には戻せず、フラグを削除して値を表示することもできません。
• シークレットには明示的なコンテキストとスコープが必要です。post processing スコープは指定できません。
• マスクされていない値を読み取れるのは Netlify 上のコード（エッジ／サーバーレス／ビルド）のみです。Netlify 外ではマスクされた値が表示されます。dev コンテキストの値は例外で、UI／CLI／API からマスクされていない値を取得できます。netlify build が生の値を出力することはありません。

シークレットスキャンは、いずれかの変数がシークレットになると自動的に実行されます（スマート検出による実行もあります）。検出されるとビルドは失敗し、場所がログに記録されます。コンテキストごとに設定する環境変数で構成します。

• SECRETS_SCAN_ENABLED=false — すべてのスキャンを無効にします（すべてのシークレット保護が失われます）。
• SECRETS_SCAN_SMART_DETECTION_ENABLED=false — スマート検出のみを無効にします。
• SECRETS_SCAN_OMIT_KEYS、SECRETS_SCAN_OMIT_PATHS（カンマ区切りのリスト。パスはリポジトリのルートから指定し、glob も使用できます）。
• SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES — 誤検出をセーフリストに登録します（無効化するよりもこちらを推奨します）。スマート検出は Personal／Pro／Enterprise で利用できます。

スキャン対象はすべてのビルドファイルです。4 文字を超える値とブール値以外の値について、プレーンテキスト、base64、URI エンコードの各形式を検索します。

機密変数ポリシー（公開リポジトリのみ）

信頼されていないデプロイ（認識されない作成者）に機密変数を提供するかどうかを制御します。サイトメンバーによる Git デプロイは、フォークからのものも常に信頼されます。Project configuration > Environment variables > Site policies で設定します。

• 承認を必須にする（デフォルト）— 信頼されていないデプロイは、メンバーの承認を待ちます。
• 機密変数を使わずにデプロイ — ビルドは実行されますが、機密変数は提供されません。
• 制限なしでデプロイ — すべての変数が提供されます。

GitHub Enterprise Server／GitLab self-managed リポジトリでは利用できません（非公開として扱われます）。

ビルドを無視する

[build] の ignore は、再ビルドするかどうかを決定します。ベースディレクトリから Bash（または固定の Node.js 18）で実行されます（サイトの package.json の依存関係は利用できません）。終了コード 1 = 変更あり → ビルドを続行。終了コード 0 = 変更なし → ビルドを停止。 ビルドフックは終了コードにかかわらず、常にビルドを実行します。

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common"

[build]
  ignore = "node ignore_build.js"   # separate file paths must start with ./

// ignore_build.js
process.exitCode = process.env.BRANCH.includes("debug") ? 0 : 1

モノレポ

サイトのサブディレクトリをパッケージディレクトリに設定し（その場所に netlify.toml を置いたままにします）、ベースはルート / のままにして、依存関係はサブディレクトリのレベルで宣言します。パッケージディレクトリはUI 専用であり、netlify.toml では設定できません（Project configuration > Developer settings > Continuous deployment > Build settings）。設定ファイルは、パッケージディレクトリ → ベースディレクトリ → ルートの順に検索されます。netlify.toml のパスは、ベースディレクトリを基準とする絶対パスのままです。netlify <cmd> --filter <site> でサイトを選択します。

JavaScript SPA

ビルドコマンドは npm run <script> ／ yarn <script> です。公開ディレクトリは多くの場合 dist です（フレームワークによって異なります）。pushState ルーティングを使用する場合は、上記の /* /index.html 200 フォールバックを追加します。コード分割とハッシュ付きファイル名をアトミックデプロイと組み合わせると、古い参照で Uncaught SyntaxError: Unexpected token が発生することがあります。ハッシュ付きファイル名を無効にする、パーマリンクを使用する、またはサービスワーカーを使用してください。

Netlify Dev [dev]

Bash では実行されません（command で Bash 構文は使用できません）。environment キーはありません。ローカルの環境変数は [context.dev.environment] の下に設定します。

[dev]
  command = "yarn start"
  targetPort = 3000        # if both command + targetPort set, framework must be "#custom"
  port = 8888
  framework = "#custom"
  [dev.https]
    certFile = "cert.pem"
    keyFile = "key.pem"

プラグインと拡張機能

[[plugins]]
package = "netlify-plugin-check-output-for-puppy-references"
  [plugins.inputs]
  breeds = ["pomeranian", "chihuahua"]

[[integrations]]              # build-time extension; install on team first
  name = "abc-performance-extension"
  [integrations.config]
    output_path = "reports/performance-reports.html"

完全なリファレンスページ：ビルド環境変数は https://docs.netlify.com/build/configure-builds/environment-variables.md、環境変数の概要は https://docs.netlify.com/build/environment-variables/overview.md、Secrets Controller は https://docs.netlify.com/build/environment-variables/secrets-controller.md、リダイレクトは https://docs.netlify.com/manage/routing/redirects/overview.md、リダイレクトのオプションは https://docs.netlify.com/manage/routing/redirects/redirect-options.md、リライト／プロキシは https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md、カスタムヘッダーは https://docs.netlify.com/manage/routing/headers.md、ファイルベースの設定は https://docs.netlify.com/build/configure-builds/file-based-configuration.md。

Netlify の内部ルール（設定）

これらはドキュメントの事実ではなく、組織内の規約です。ctx-gen によってレンダリング済みのスキルに統合され、生成されることはありません。スキルのメンテナーが管理します。

1. netlify.toml で設定した環境変数は、実行時に関数やエッジ関数からは利用できません。そこで読み取ると undefined が返されます。実行時の環境変数は UI または netlify env:set で設定し、netlify.toml には設定しないでください。
2. クライアント向けプレフィックスが付いた環境変数（VITE_、NEXT_PUBLIC_、PUBLIC_ など）には、シークレットを絶対に設定しないでください。これらはクライアントバンドルにインライン化されるため、--secret でも保護されません。
3. 環境変数をローカルに保存する場合（netlify env:list --plain > .env）、.env を必ず gitignore に追加し、絶対にコミットしないでください。
4. 環境変数のスコープ間の相互作用を明示してください。Builds スコープに設定されたサイト変数は、ほかのスコープの共有変数を上書きしません。優先順位はスコープごとに個別に解決されます（サイト変数が共有変数より優先されるのは、サイト変数が実際に適用されるスコープ内に限られます）。