尧图网页设计 
netlify.toml 完全配置指南Netlify 构建与部署的声明式基础【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsnetlify.toml是 Netlify 基于文件的配置入口位于仓库根目录用声明式 TOML 语法集中定义构建命令、发布目录、环境变量、重定向、响应头、Serverless Functions、Edge Functions 与构建插件等全部部署行为。本文完整梳理该文件的核心配置项与参数语义并串联本仓库 netlify-deploy 技能 中的 CLI 工作流与部署模式帮助你写出可复制、可维护、可被 Agent 自动化执行的部署配置。基本结构构建与发布的最小声明netlify.toml的最小可用配置只需要两个键构建命令与发布目录。Netlify CLI 在每次部署时读取该文件执行command完成构建然后把publish指向的产物目录上传到 CDN。[build] command npm run build publish dist这两项对应 SKILL.md 中描述的 CLI 交互逻辑如果仓库中存在netlify.tomlCLI 会自动读取而不再询问若文件缺失CLI 才会交互式地提示用户填写 Build command 与 Publish directory。Build 设置详解[build]表格是配置的核心支持以下常用键[build] # Command to build your site command npm run build # Directory to publish (relative to repo root) publish dist # Functions directory functions netlify/functions # Base directory (if not repo root) base packages/frontend # Ignore builds for specific conditions ignore git diff --quiet HEAD^ HEAD package.json各键的作用与适用场景command构建命令。Netlify 会在构建环境中执行该 shell 命令产物必须落入publish指定目录否则部署会以 Publish directory not found 失败见 deployment-patterns.md 的恢复模式。publish相对仓库根目录的静态产物目录例如 Vite 项目的dist、Next.js 的.next、SvelteKit 的build。functionsServerless Functions 源码目录。该目录下的每个文件会被视为一个函数端点配合npx netlify functions:list可本地列出全部函数见 cli-commands.md。base当项目位于 Monorepo 子目录而非仓库根目录时指定构建的工作目录所有相对路径command、publish都以它为基准。ignore构建跳过条件。命令返回非零退出码时跳过本次构建例如 CI 中只有package.json变化才需要重建的场景。该参数与 cli-commands.md 中描述的 CLI 退出码约定共同构成按需构建的判定基础。环境变量构建期与应用期分离环境变量可以放在构建环境或特定部署上下文中。[build.environment]作用于所有构建[context.上下文.environment]只作用于对应上下文且后者优先。[build.environment] NODE_VERSION 18 NPM_FLAGS --prefix/dev/null [context.production.environment] NODE_ENV productionNODE_VERSION锁定构建环境的 Node 主版本避免本地与云端 Node 版本不一致导致构建行为漂移。NPM_FLAGS透传给 npm 的附加参数。NODE_ENV生产上下文专用的环境标记常见于依赖环境区分构建产物如 tree-shaking、压缩的项目。关于密钥类环境变量SKILL.md 强调三条铁律密钥永不提交到 Git在 Netlify Dashboard 的 Site Settings → Environment Variables 中设置代码中通过process.env.VARIABLE_NAME读取。CLI 也提供了对等的管理命令npx netlify env:set KEY value、env:get、env:list与env:import .env见 cli-commands.md。框架检测与覆盖Netlify 会根据仓库内容自动检测框架并填充默认构建命令与发布目录本技能则建议优先从package.json推断框架见 SKILL.md。当自动检测不准确、需要自定义构建命令或项目结构非常规时应在[build]中显式覆盖。常见框架的等效配置如下# Next.js [build] command npm run build publish .next # React (Vite) [build] command npm run build publish dist # Vue [build] command npm run build publish dist # Astro [build] command npm run build publish dist # SvelteKit [build] command npm run build publish build要点Next.js 的产物目录是.nextSvelteKit 是build而 Vite/Vue/Astro 均默认输出dist。若 CLI 检测不到框架会直接采用上述默认建议值SKILL.md对于无构建步骤的纯静态 HTML 项目可省去command直接publish当前目录。重定向与重写Redirects Rewrites[[redirects]]是数组语法注意双括号可同时用于路径级重定向301与 API 代理重写200还支持通配符与 SPA 回退[[redirects]] from /old-path to /new-path status 301 [[redirects]] from /api/* to https://api.example.com/:splat status 200 # SPA fallback (for client-side routing) [[redirects]] from /* to /index.html status 200规则解释301 永久重定向用于旧路径迁移同时利于搜索引擎收录新地址。200 重写代理status 200时不改变浏览器地址栏由 Netlify 边缘将/api/*反向代理到:splat捕获的完整通配符路径适合隐藏上游 API 域名或聚合后端服务。SPA 回退from /*配合to /index.html将所有未匹配路径交给前端路由是客户端路由React Router、Vue Router 等在 Netlify 上正常运行的前提。[[redirects]]还支持基于条件的路由见下文常见模式中的国家地区分流可结合status 302实现临时跳转。自定义响应头Headers[[headers]]数组为指定路径模式附加 HTTP 响应头常用于安全加固与静态资源缓存[[headers]] for /* [headers.values] X-Frame-Options DENY X-XSS-Protection 1; modeblock Content-Security-Policy default-src self [[headers]] for /assets/* [headers.values] Cache-Control public, max-age31536000, immutable全局安全头X-Frame-Options: DENY防止点击劫持X-XSS-Protection启用浏览器 XSS 过滤Content-Security-Policy收紧资源来源。注意首条规则for /*会作用于所有路径。静态资源长缓存Cache-Control: public, max-age31536000, immutable表示一年内不可变缓存适合带内容哈希文件名的构建产物如assets/app.8f3d2a.js。这条模式同样出现在 deployment-patterns.md 的性能建议中。上下文特定配置Context-SpecificNetlify 支持按部署上下文覆盖构建命令与环境变量实现一套文件、多环境策略# Production [context.production] command npm run build:prod [context.production.environment] NODE_ENV production # Deploy previews [context.deploy-preview] command npm run build:preview # Branch deploys [context.branch-deploy] command npm run build:staging # Specific branch [context.staging] command npm run build:staging各上下文与 SKILL.md 的部署流程一一对应productionnpx netlify deploy --prod触发使用生产构建命令与NODE_ENVproduction。deploy-previewnpx netlify deploy生成的带唯一 URL 的草稿预览使用预览构建命令便于上线前测试。branch-deploy非主分支的分支部署。任意具名分支如[context.staging]针对名为staging的分支生效适合预发布环境。当上下文中未显式指定command时将回退到[build]的全局值因此最佳实践是只覆盖需要差异化的键。Serverless Functions 配置[functions]表格设置函数构建与打包方式[[functions]]数组则用于定义路径到函数的映射[functions] directory netlify/functions node_bundler esbuild [[functions]] path /api/* function apidirectory函数源码目录与[build].functions作用等价。node_bundlerNode.js 函数打包器设为esbuild可获得更快的打包速度与更小的产物相比默认的 zip-it-and-ship-it 内置打包。[[functions]]映射将/api/*的请求路由到名为api的函数处理。也可仅在函数源码目录放置文件Netlify 会自动以文件名生成端点/api/hello对应hello.js。配套的 CLI 能力见 cli-commands.mdnpx netlify functions:create生成函数脚手架functions:invoke本地调用函数npx netlify logs:function流式查看函数日志本地联调推荐npx netlify dev自带函数运行时SKILL.md。构建插件Build Plugins[[plugins]]数组引入第三方构建插件并用[plugins.inputs]传参[[plugins]] package netlify/plugin-lighthouse [plugins.inputs] output_path reports/lighthouse.html [[plugins]] package netlify-plugin-submit-sitemap [plugins.inputs] baseUrl https://example.com sitemapPath /sitemap.xmlnetlify/plugin-lighthouse部署后自动对站点运行 Lighthouse 审计并输出报告reports/lighthouse.html用于性能与 SEO 门槛检查。netlify-plugin-submit-sitemap构建完成后将站点地图提交给搜索引擎baseUrl指定站点域名sitemapPath指定 sitemap 相对路径。插件在构建生命周期中按声明顺序执行可参考 Netlify 的 netlify.toml 官方参考。当前仓库内未捆绑第三方插件代码具体插件行为以各插件包文档为准。Edge Functions 配置Edge Functions 运行在 Netlify 全球边缘网络适合地理定位、A/B 测试、请求改写等低延迟场景[[edge_functions]] function geolocation path /api/location该配置将名为geolocation的边缘函数绑定到/api/location路径请求到达边缘节点时先执行函数逻辑再返回响应。注意 Edge Functions 与 Serverless Functions 的定位差异前者是边缘运行时靠近用户、延迟低后者是传统 Node.js 函数能力更全选择取决于延迟敏感度与运行环境需求。构建后处理ProcessingNetlify 可对构建产物做自动化的后处理优化全部通过[build.processing]启用[build.processing] skip_processing false [build.processing.css] bundle true minify true [build.processing.js] bundle true minify true [build.processing.html] pretty_urls true [build.processing.images] compress trueskip_processing设为true时跳过全部后处理如对已高度优化的产物避免二次变换。CSS/JSbundle合并资源文件减少请求数minify压缩体积。这两项也在 deployment-patterns.md 中被列为性能优化首选。HTMLpretty_urls将/about.html映射为/about/风格的美观 URL。Imagescompress在 CDN 边缘对图片做无损压缩减小传输体积。常见模式Common Patterns以下三种模式可直接复制到项目中覆盖大部分真实部署场景。单页应用SPA[build] command npm run build publish dist [[redirects]] from /* to /index.html status 200构建后配合全路径回退重写保证前端路由如/users/42刷新时不 404。这也是 deployment-patterns.md 推荐写入仓库根目录的一致性配置。Monorepo 子目录构建[build] base packages/web command npm run build publish dist适用于仓库包含多个包、仅部署packages/web的场景。配合 deployment-patterns.md 中的做法CI 或本地也可先cd packages/frontend再部署两种方式等价。基于国家地区的多规则路由[[redirects]] from / to /uk status 302 conditions {Country [GB]} [[redirects]] from / to /us status 302 conditions {Country [US]}conditions支持按国家代码Country匹配请求来源status 302临时重定向到对应区域首页。多条规则按顺序求值先匹配的先生效适用于国际站点的地区分流。配置校验与本地验证写完后应先本地校验再部署避免把配置错误带到线上npx netlify build --dry--dry模式只解析并展示构建配置不真正执行构建是验证netlify.toml语法与参数的最快途径。进一步的验证手段还包括见 cli-commands.mdnpx netlify build在本地完整模拟远程构建提前暴露 Command failed with exit code 1 等问题恢复步骤见 deployment-patterns.md。npx netlify dev本地启动带 Functions、重定向等 Netlify 特性的开发服务器--port可指定端口。npx netlify deploy不带--prod先发布草稿预览验证 URL再npx netlify deploy --prod上生产——这是 SKILL.md 明确推荐的先预览、后生产节奏。与 netlify-deploy 技能的结合netlify.toml与本仓库的 netlify-deploy 技能 是一体两面技能负责自动化决策认证检查 → 站点关联 → 依赖安装 → 选择预览/生产部署而配置文件负责承载确定性配置。技能在处理配置时会遵循 SKILL.md 的规则检测到netlify.toml则直接复用缺失时才根据框架默认值Next.js 用.next、Vite 用dist引导生成。因此将本文的配置片段写入仓库根目录的netlify.toml即可让本地构建、CI 构建与 Agent 自动化部署三者共享同一份构建契约实现跨环境的可复现发布。相关参考材料可继续查阅仓库内的 CLI 命令速查 与 部署模式与最佳实践。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 netlify.toml 完全配置指南：Netlify 构建与部署的声明式基础
netlify.toml 完全配置指南Netlify 构建与部署的声明式基础【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsnetlify.toml是 Netlify 基于文件的配置入口位于仓库根目录用声明式 TOML 语法集中定义构建命令、发布目录、环境变量、重定向、响应头、Serverless Functions、Edge Functions 与构建插件等全部部署行为。本文完整梳理该文件的核心配置项与参数语义并串联本仓库 netlify-deploy 技能 中的 CLI 工作流与部署模式帮助你写出可复制、可维护、可被 Agent 自动化执行的部署配置。基本结构构建与发布的最小声明netlify.toml的最小可用配置只需要两个键构建命令与发布目录。Netlify CLI 在每次部署时读取该文件执行command完成构建然后把publish指向的产物目录上传到 CDN。[build] command npm run build publish dist这两项对应 SKILL.md 中描述的 CLI 交互逻辑如果仓库中存在netlify.tomlCLI 会自动读取而不再询问若文件缺失CLI 才会交互式地提示用户填写 Build command 与 Publish directory。Build 设置详解[build]表格是配置的核心支持以下常用键[build] # Command to build your site command npm run build # Directory to publish (relative to repo root) publish dist # Functions directory functions netlify/functions # Base directory (if not repo root) base packages/frontend # Ignore builds for specific conditions ignore git diff --quiet HEAD^ HEAD package.json各键的作用与适用场景command构建命令。Netlify 会在构建环境中执行该 shell 命令产物必须落入publish指定目录否则部署会以 Publish directory not found 失败见 deployment-patterns.md 的恢复模式。publish相对仓库根目录的静态产物目录例如 Vite 项目的dist、Next.js 的.next、SvelteKit 的build。functionsServerless Functions 源码目录。该目录下的每个文件会被视为一个函数端点配合npx netlify functions:list可本地列出全部函数见 cli-commands.md。base当项目位于 Monorepo 子目录而非仓库根目录时指定构建的工作目录所有相对路径command、publish都以它为基准。ignore构建跳过条件。命令返回非零退出码时跳过本次构建例如 CI 中只有package.json变化才需要重建的场景。该参数与 cli-commands.md 中描述的 CLI 退出码约定共同构成按需构建的判定基础。环境变量构建期与应用期分离环境变量可以放在构建环境或特定部署上下文中。[build.environment]作用于所有构建[context.上下文.environment]只作用于对应上下文且后者优先。[build.environment] NODE_VERSION 18 NPM_FLAGS --prefix/dev/null [context.production.environment] NODE_ENV productionNODE_VERSION锁定构建环境的 Node 主版本避免本地与云端 Node 版本不一致导致构建行为漂移。NPM_FLAGS透传给 npm 的附加参数。NODE_ENV生产上下文专用的环境标记常见于依赖环境区分构建产物如 tree-shaking、压缩的项目。关于密钥类环境变量SKILL.md 强调三条铁律密钥永不提交到 Git在 Netlify Dashboard 的 Site Settings → Environment Variables 中设置代码中通过process.env.VARIABLE_NAME读取。CLI 也提供了对等的管理命令npx netlify env:set KEY value、env:get、env:list与env:import .env见 cli-commands.md。框架检测与覆盖Netlify 会根据仓库内容自动检测框架并填充默认构建命令与发布目录本技能则建议优先从package.json推断框架见 SKILL.md。当自动检测不准确、需要自定义构建命令或项目结构非常规时应在[build]中显式覆盖。常见框架的等效配置如下# Next.js [build] command npm run build publish .next # React (Vite) [build] command npm run build publish dist # Vue [build] command npm run build publish dist # Astro [build] command npm run build publish dist # SvelteKit [build] command npm run build publish build要点Next.js 的产物目录是.nextSvelteKit 是build而 Vite/Vue/Astro 均默认输出dist。若 CLI 检测不到框架会直接采用上述默认建议值SKILL.md对于无构建步骤的纯静态 HTML 项目可省去command直接publish当前目录。重定向与重写Redirects Rewrites[[redirects]]是数组语法注意双括号可同时用于路径级重定向301与 API 代理重写200还支持通配符与 SPA 回退[[redirects]] from /old-path to /new-path status 301 [[redirects]] from /api/* to https://api.example.com/:splat status 200 # SPA fallback (for client-side routing) [[redirects]] from /* to /index.html status 200规则解释301 永久重定向用于旧路径迁移同时利于搜索引擎收录新地址。200 重写代理status 200时不改变浏览器地址栏由 Netlify 边缘将/api/*反向代理到:splat捕获的完整通配符路径适合隐藏上游 API 域名或聚合后端服务。SPA 回退from /*配合to /index.html将所有未匹配路径交给前端路由是客户端路由React Router、Vue Router 等在 Netlify 上正常运行的前提。[[redirects]]还支持基于条件的路由见下文常见模式中的国家地区分流可结合status 302实现临时跳转。自定义响应头Headers[[headers]]数组为指定路径模式附加 HTTP 响应头常用于安全加固与静态资源缓存[[headers]] for /* [headers.values] X-Frame-Options DENY X-XSS-Protection 1; modeblock Content-Security-Policy default-src self [[headers]] for /assets/* [headers.values] Cache-Control public, max-age31536000, immutable全局安全头X-Frame-Options: DENY防止点击劫持X-XSS-Protection启用浏览器 XSS 过滤Content-Security-Policy收紧资源来源。注意首条规则for /*会作用于所有路径。静态资源长缓存Cache-Control: public, max-age31536000, immutable表示一年内不可变缓存适合带内容哈希文件名的构建产物如assets/app.8f3d2a.js。这条模式同样出现在 deployment-patterns.md 的性能建议中。上下文特定配置Context-SpecificNetlify 支持按部署上下文覆盖构建命令与环境变量实现一套文件、多环境策略# Production [context.production] command npm run build:prod [context.production.environment] NODE_ENV production # Deploy previews [context.deploy-preview] command npm run build:preview # Branch deploys [context.branch-deploy] command npm run build:staging # Specific branch [context.staging] command npm run build:staging各上下文与 SKILL.md 的部署流程一一对应productionnpx netlify deploy --prod触发使用生产构建命令与NODE_ENVproduction。deploy-previewnpx netlify deploy生成的带唯一 URL 的草稿预览使用预览构建命令便于上线前测试。branch-deploy非主分支的分支部署。任意具名分支如[context.staging]针对名为staging的分支生效适合预发布环境。当上下文中未显式指定command时将回退到[build]的全局值因此最佳实践是只覆盖需要差异化的键。Serverless Functions 配置[functions]表格设置函数构建与打包方式[[functions]]数组则用于定义路径到函数的映射[functions] directory netlify/functions node_bundler esbuild [[functions]] path /api/* function apidirectory函数源码目录与[build].functions作用等价。node_bundlerNode.js 函数打包器设为esbuild可获得更快的打包速度与更小的产物相比默认的 zip-it-and-ship-it 内置打包。[[functions]]映射将/api/*的请求路由到名为api的函数处理。也可仅在函数源码目录放置文件Netlify 会自动以文件名生成端点/api/hello对应hello.js。配套的 CLI 能力见 cli-commands.mdnpx netlify functions:create生成函数脚手架functions:invoke本地调用函数npx netlify logs:function流式查看函数日志本地联调推荐npx netlify dev自带函数运行时SKILL.md。构建插件Build Plugins[[plugins]]数组引入第三方构建插件并用[plugins.inputs]传参[[plugins]] package netlify/plugin-lighthouse [plugins.inputs] output_path reports/lighthouse.html [[plugins]] package netlify-plugin-submit-sitemap [plugins.inputs] baseUrl https://example.com sitemapPath /sitemap.xmlnetlify/plugin-lighthouse部署后自动对站点运行 Lighthouse 审计并输出报告reports/lighthouse.html用于性能与 SEO 门槛检查。netlify-plugin-submit-sitemap构建完成后将站点地图提交给搜索引擎baseUrl指定站点域名sitemapPath指定 sitemap 相对路径。插件在构建生命周期中按声明顺序执行可参考 Netlify 的 netlify.toml 官方参考。当前仓库内未捆绑第三方插件代码具体插件行为以各插件包文档为准。Edge Functions 配置Edge Functions 运行在 Netlify 全球边缘网络适合地理定位、A/B 测试、请求改写等低延迟场景[[edge_functions]] function geolocation path /api/location该配置将名为geolocation的边缘函数绑定到/api/location路径请求到达边缘节点时先执行函数逻辑再返回响应。注意 Edge Functions 与 Serverless Functions 的定位差异前者是边缘运行时靠近用户、延迟低后者是传统 Node.js 函数能力更全选择取决于延迟敏感度与运行环境需求。构建后处理ProcessingNetlify 可对构建产物做自动化的后处理优化全部通过[build.processing]启用[build.processing] skip_processing false [build.processing.css] bundle true minify true [build.processing.js] bundle true minify true [build.processing.html] pretty_urls true [build.processing.images] compress trueskip_processing设为true时跳过全部后处理如对已高度优化的产物避免二次变换。CSS/JSbundle合并资源文件减少请求数minify压缩体积。这两项也在 deployment-patterns.md 中被列为性能优化首选。HTMLpretty_urls将/about.html映射为/about/风格的美观 URL。Imagescompress在 CDN 边缘对图片做无损压缩减小传输体积。常见模式Common Patterns以下三种模式可直接复制到项目中覆盖大部分真实部署场景。单页应用SPA[build] command npm run build publish dist [[redirects]] from /* to /index.html status 200构建后配合全路径回退重写保证前端路由如/users/42刷新时不 404。这也是 deployment-patterns.md 推荐写入仓库根目录的一致性配置。Monorepo 子目录构建[build] base packages/web command npm run build publish dist适用于仓库包含多个包、仅部署packages/web的场景。配合 deployment-patterns.md 中的做法CI 或本地也可先cd packages/frontend再部署两种方式等价。基于国家地区的多规则路由[[redirects]] from / to /uk status 302 conditions {Country [GB]} [[redirects]] from / to /us status 302 conditions {Country [US]}conditions支持按国家代码Country匹配请求来源status 302临时重定向到对应区域首页。多条规则按顺序求值先匹配的先生效适用于国际站点的地区分流。配置校验与本地验证写完后应先本地校验再部署避免把配置错误带到线上npx netlify build --dry--dry模式只解析并展示构建配置不真正执行构建是验证netlify.toml语法与参数的最快途径。进一步的验证手段还包括见 cli-commands.mdnpx netlify build在本地完整模拟远程构建提前暴露 Command failed with exit code 1 等问题恢复步骤见 deployment-patterns.md。npx netlify dev本地启动带 Functions、重定向等 Netlify 特性的开发服务器--port可指定端口。npx netlify deploy不带--prod先发布草稿预览验证 URL再npx netlify deploy --prod上生产——这是 SKILL.md 明确推荐的先预览、后生产节奏。与 netlify-deploy 技能的结合netlify.toml与本仓库的 netlify-deploy 技能 是一体两面技能负责自动化决策认证检查 → 站点关联 → 依赖安装 → 选择预览/生产部署而配置文件负责承载确定性配置。技能在处理配置时会遵循 SKILL.md 的规则检测到netlify.toml则直接复用缺失时才根据框架默认值Next.js 用.next、Vite 用dist引导生成。因此将本文的配置片段写入仓库根目录的netlify.toml即可让本地构建、CI 构建与 Agent 自动化部署三者共享同一份构建契约实现跨环境的可复现发布。相关参考材料可继续查阅仓库内的 CLI 命令速查 与 部署模式与最佳实践。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考