部署配置 #

配置文件概述 #

Netlify 支持通过 netlify.toml 文件进行项目配置，实现配置即代码。

配置文件位置 #

text

项目根目录/
├── netlify.toml    ← 主配置文件
├── package.json
└── src/

基础结构 #

toml

# netlify.toml

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "18"

[[redirects]]
  from = "/old"
  to = "/new"
  status = 301

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"

构建配置 #

基础构建设置 #

toml

[build]
  # 构建命令
  command = "npm run build"
  
  # 发布目录
  publish = "dist"
  
  # 函数目录
  functions = "netlify/functions"
  
  # 忽略构建的命令（返回非0则跳过构建）
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ."

构建命令详解 #

项目类型	command	publish
React (CRA)	`npm run build`	`build`
Vue (Vite)	`npm run build`	`dist`
Next.js	`npm run build`	`.next`
Hugo	`hugo`	`public`
Hexo	`hexo generate`	`public`
Gatsby	`gatsby build`	`public`
Astro	`npm run build`	`dist`

环境变量配置 #

toml

[build.environment]
  # Node.js 版本
  NODE_VERSION = "18"
  
  # NPM 版本
  NPM_VERSION = "9"
  
  # Yarn 版本
  YARN_VERSION = "1.22"
  
  # 自定义环境变量
  MY_API_KEY = "production-key"

多环境构建 #

toml

# 生产环境
[context.production]
  command = "npm run build:prod"
  [context.production.environment]
    NODE_ENV = "production"

# 预览环境（Deploy Preview）
[context.deploy-preview]
  command = "npm run build:preview"
  [context.deploy-preview.environment]
    NODE_ENV = "preview"

# 分支部署
[context.branch-deploy]
  command = "npm run build:staging"
  [context.branch-deploy.environment]
    NODE_ENV = "staging"

# 特定分支配置
[context.staging]
  command = "npm run build:staging"

重定向规则 #

基本重定向 #

toml

[[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301

重定向状态码 #

状态码	含义	用途
301	永久重定向	页面永久移动
302	临时重定向	临时跳转
307	临时重定向（保留方法）	API 重定向
308	永久重定向（保留方法）	API 永久移动

通配符重定向 #

toml

# 所有旧博客文章重定向到新路径
[[redirects]]
  from = "/blog/*"
  to = "/posts/:splat"
  status = 301

# :splat 匹配 * 的内容
# /blog/hello-world → /posts/hello-world

占位符重定向 #

toml

[[redirects]]
  from = "/posts/:year/:month/:slug"
  to = "/blog/:slug?year=:year&month=:month"
  status = 302

查询参数重定向 #

toml

[[redirects]]
  from = "/search"
  to = "/search-results?q=:q"
  status = 302
  query = {q = ":q"}

强制 HTTPS #

toml

[[redirects]]
  from = "http://example.com/*"
  to = "https://example.com/:splat"
  status = 301
  force = true

SPA 路由支持 #

toml

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

按语言重定向 #

toml

[[redirects]]
  from = "/"
  to = "/en/"
  status = 302
  conditions = {Language = ["en"]}

[[redirects]]
  from = "/"
  to = "/zh/"
  status = 302
  conditions = {Language = ["zh"]}

按国家重定向 #

toml

[[redirects]]
  from = "/"
  to = "/us/"
  status = 302
  conditions = {Country = ["US", "CA"]}

[[redirects]]
  from = "/"
  to = "/cn/"
  status = 302
  conditions = {Country = ["CN"]}

重定向到外部 URL #

toml

[[redirects]]
  from = "/docs"
  to = "https://docs.example.com"
  status = 301

Headers 配置 #

基本语法 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

安全 Headers #

toml

[[headers]]
  for = "/*"
  [headers.values]
    # 防止点击劫持
    X-Frame-Options = "DENY"
    
    # XSS 保护
    X-XSS-Protection = "1; mode=block"
    
    # 内容类型嗅探保护
    X-Content-Type-Options = "nosniff"
    
    # 引用来源策略
    Referrer-Policy = "strict-origin-when-cross-origin"
    
    # 权限策略
    Permissions-Policy = "camera=(), microphone=(), geolocation=()"

Content Security Policy #

toml

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'"

缓存配置 #

toml

# 静态资源长期缓存
[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

# HTML 不缓存
[[headers]]
  for = "/*.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

# CSS/JS 中期缓存
[[headers]]
  for = "/*.css"
  [headers.values]
    Cache-Control = "public, max-age=86400"

[[headers]]
  for = "/*.js"
  [headers.values]
    Cache-Control = "public, max-age=86400"

字体文件配置 #

toml

[[headers]]
  for = "/fonts/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000"
    Access-Control-Allow-Origin = "*"

图片资源配置 #

toml

[[headers]]
  for = "/images/*"
  [headers.values]
    Cache-Control = "public, max-age=2592000"

插件配置 #

安装插件 #

toml

[[plugins]]
  package = "@netlify/plugin-lighthouse"

[[plugins]]
  package = "netlify-plugin-cache"
  [plugins.inputs]
    paths = ["node_modules", ".cache"]

常用插件 #

toml

# Lighthouse 性能检测
[[plugins]]
  package = "@netlify/plugin-lighthouse"
  [plugins.inputs]
    output_path = "reports/lighthouse"

# 缓存优化
[[plugins]]
  package = "netlify-plugin-cache"
  [plugins.inputs]
    paths = ["node_modules"]

# Sitemap 生成
[[plugins]]
  package = "@netlify/plugin-sitemap"

# 提交信息检查
[[plugins]]
  package = "netlify-plugin-commit-checker"

函数配置 #

函数目录 #

toml

[functions]
  directory = "netlify/functions"
  node_bundler = "esbuild"

函数超时设置 #

toml

[functions]
  directory = "netlify/functions"
  
[functions."scheduled-function"]
  schedule = "0 0 * * *"

边缘函数配置 #

toml

[[edge_functions]]
  function = "geolocation"
  path = "/api/location"

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

完整配置示例 #

toml

[build]
  command = "npm run build"
  publish = "dist"
  functions = "netlify/functions"

[build.environment]
  NODE_VERSION = "18"

[context.production]
  command = "npm run build:prod"
  [context.production.environment]
    NODE_ENV = "production"

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

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

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

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    X-Content-Type-Options = "nosniff"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[plugins]]
  package = "@netlify/plugin-lighthouse"

配置优先级 #

text

netlify.toml > 控制台设置 > 默认值

调试配置 #

本地测试 #

bash

netlify dev

查看有效配置 #

bash

netlify status

验证配置语法 #

bash

netlify build --dry-run

下一步 #

掌握了部署配置后，继续学习框架预设支持了解各框架的最佳实践！