Back to Details

netlify-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Netlify Configuration (netlify.toml)

Netlify配置（netlify.toml）

Place 
netlify.toml
at the repository root (or at the base directory for monorepos).
将
netlify.toml
放置在仓库根目录（或 monorepo 的基础目录）。

Build Settings

构建设置

toml
[build]
  base = "project/"          # Base directory (default: root)
  command = "npm run build"  # Build command
  publish = "dist/"          # Output directory
toml
[build]
  base = "project/"          # 基础目录（默认：根目录）
  command = "npm run build"  # 构建命令
  publish = "dist/"          # 输出目录

Redirects

重定向

toml
undefined
toml
undefined

Basic redirect

基础重定向

[[redirects]] from = "/old" to = "/new" status = 301 # 301 (default), 302, 200 (rewrite), 404
[[redirects]] from = "/old" to = "/new" status = 301 # 301（默认）、302、200（重写）、404

SPA catch-all

SPA 全局捕获

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

Splat (wildcard)

通配符（Splat）

[[redirects]] from = "/blog/*" to = "/news/:splat"
[[redirects]] from = "/blog/*" to = "/news/:splat"

Path parameters

路径参数

[[redirects]] from = "/users/:id" to = "/api/users/:id" status = 200
[[redirects]] from = "/users/:id" to = "/api/users/:id" status = 200

Force (override existing files)

强制覆盖（忽略现有文件）

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

Proxy to external service

代理到外部服务

[[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 [redirects.headers] X-Custom = "value"
[[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 [redirects.headers] X-Custom = "value"

Country/language conditions

国家/语言条件

[[redirects]] from = "/*" to = "/fr/:splat" status = 200 conditions = { Country = ["FR"], Language = ["fr"] }

**Rule order matters** — Netlify processes the first matching rule. Place specific rules before general ones.
[[redirects]] from = "/*" to = "/fr/:splat" status = 200 conditions = { Country = ["FR"], Language = ["fr"] }

**规则顺序很重要** —— Netlify 会处理第一个匹配的规则。请将特定规则放在通用规则之前。

Headers

响应头

toml
[[headers]]
for = "/*"
[headers.values]
  X-Frame-Options = "DENY"
  X-Content-Type-Options = "nosniff"

[[headers]]
for = "/assets/*"
[headers.values]
  Cache-Control = "public, max-age=31536000, immutable"
Headers apply only to files served from Netlify's CDN (not to function or edge function responses — set those in code).
toml
[[headers]]
for = "/*"
[headers.values]
  X-Frame-Options = "DENY"
  X-Content-Type-Options = "nosniff"

[[headers]]
for = "/assets/*"
[headers.values]
  Cache-Control = "public, max-age=31536000, immutable"
响应头仅适用于从 Netlify CDN 提供的文件（不适用于函数或边缘函数的响应——需在代码中设置）。

Deploy Contexts

部署环境

Override settings per deploy context:
toml
[context.production]
command = "npm run build"
environment = { NODE_ENV = "production" }

[context.deploy-preview]
command = "npm run build:preview"

[context.branch-deploy]
command = "npm run build:staging"

[context.dev]
environment = { NODE_ENV = "development" }
按部署环境覆盖设置：
toml
[context.production]
command = "npm run build"
environment = { NODE_ENV = "production" }

[context.deploy-preview]
command = "npm run build:preview"

[context.branch-deploy]
command = "npm run build:staging"

[context.dev]
environment = { NODE_ENV = "development" }

Specific branch

特定分支

[context."staging"] command = "npm run build:staging"
undefined
[context."staging"] command = "npm run build:staging"
undefined

Environment Variables

环境变量

toml
[build.environment]
NODE_VERSION = "20"

[context.production.environment]
API_URL = "https://api.prod.com"

[context.deploy-preview.environment]
API_URL = "https://api.staging.com"
Do not put secrets in netlify.toml (it's committed to source control). Use the Netlify UI or CLI for sensitive values. See the netlify-cli-and-deploy skill for CLI environment variable management.
toml
[build.environment]
NODE_VERSION = "20"

[context.production.environment]
API_URL = "https://api.prod.com"

[context.deploy-preview.environment]
API_URL = "https://api.staging.com"
请勿在netlify.toml中存放敏感信息（它会被提交到版本控制系统）。请使用Netlify UI或CLI管理敏感值。有关CLI环境变量管理，请查看netlify-cli-and-deploy技能文档。

Functions Configuration

函数配置

toml
[functions]
directory = "netlify/functions"   # Default
node_bundler = "esbuild"
toml
[functions]
directory = "netlify/functions"   # 默认路径
node_bundler = "esbuild"

Scheduled function

定时函数

[functions."cleanup"] schedule = "@daily"
undefined
[functions."cleanup"] schedule = "@daily"
undefined

Edge Functions Configuration

边缘函数配置

toml
[[edge_functions]]
path = "/admin"
function = "auth"
toml
[[edge_functions]]
path = "/admin"
function = "auth"

Import map for Deno URL imports

Deno URL 导入的导入映射

[functions] deno_import_map = "./import_map.json"
undefined
[functions] deno_import_map = "./import_map.json"
undefined

Dev Server

开发服务器

toml
[dev]
command = "npm start"       # Dev server command
port = 8888                 # Netlify Dev port
targetPort = 3000           # Your app's dev server port
framework = "#auto"         # "#auto", "#static", "#custom"
toml
[dev]
command = "npm start"       # 开发服务器命令
port = 8888                 # Netlify Dev 端口
targetPort = 3000           # 你的应用开发服务器端口
framework = "#auto"         # "#auto"、"#static"、"#custom"

Plugins

插件

toml
[[plugins]]
package = "@netlify/plugin-lighthouse"
[plugins.inputs]
  audits = ["performance", "accessibility"]
toml
[[plugins]]
package = "@netlify/plugin-lighthouse"
[plugins.inputs]
  audits = ["performance", "accessibility"]

Image CDN

图片CDN

toml
[images]
remote_images = ["https://example\\.com/.*"]
See the netlify-image-cdn skill for full Image CDN usage.
toml
[images]
remote_images = ["https://example\\.com/.*"]
有关图片CDN的完整用法，请查看netlify-image-cdn技能文档。