1. 为什么你的 Netlify 重定向总是不生效如果你正在用 Netlify 部署静态站点大概率会遇到这样的场景网站改版后旧链接全部 404或者单页应用刷新子路由直接白屏。这时候你需要的就是 Netlify 重定向。它是一套运行在 CDN 边缘节点的规则引擎能在请求到达你的静态资源之前根据预设规则决定请求的最终去向。适合所有用 Netlify 托管前端项目的开发者尤其是用 React、Vue、Astro 做 SPA 或 SSG 的同学。我见过太多人把_redirects文件往项目根目录一扔就以为完事了结果部署上去发现规则根本没被读取。原因很简单Netlify 读取的是构建输出目录里的_redirects不是源码根目录。如果你用的是 Vite输出目录是dist用 Next.js 静态导出输出目录是out用 Hugo输出目录是public。文件放错位置规则永远不会生效。另一个高频翻车点是规则顺序。Netlify 按从上到下的顺序匹配一旦命中就停止。很多人把通配规则写在最前面导致后面所有具体规则都成了摆设。比如你先写了/* /index.html 200那后面所有 301 跳转都不会被执行因为所有请求都被这条兜底规则截胡了。还有一个容易被忽略的细节_redirects文件和netlify.toml同时存在时两者的规则会合并但netlify.toml里的规则优先级更高。如果你在两个地方都写了规则排查问题时需要同时检查两个文件。这篇文章会从零开始把_redirects文件写法、netlify.toml结构化配置、SPA 兜底、404 处理、状态码选择、优先级验证这几个环节全部串起来。每个配置片段都可以直接复制到你的项目里用部署后我会告诉你怎么逐条验证跳转状态码确认规则真的按预期执行了。2. 动手前的准备TaoToken 接入与项目环境确认在开始配置重定向之前你需要先确认两件事一是你的 Netlify 项目已经正常部署二是如果你打算在重定向目标里接入 AI 能力比如把某些路径代理到模型接口需要先拿到可用的 API 凭证。这里我用 TaoToken 作为示例它的接口兼容 OpenAI 格式配置起来比较直接。首先确认你的 Netlify 项目结构。打开项目根目录看看构建命令和发布目录是什么。在netlify.toml里通常长这样[build] command npm run build publish dist这里的publish就是 Netlify 读取_redirects的目录。如果你没有netlify.toml可以在 Netlify 后台的 Site settings Build deploy 里看到发布目录。记住这个路径后面放_redirects文件就靠它。接下来拿 TaoToken 的 API Key。访问https://taotoken.net/api-keys注册并创建一个 Key格式类似sk-xxxxxxxx。这个 Key 后面会用在环境变量里不要硬编码到前端代码中。在 Netlify 后台的 Site settings Environment variables 里添加一个变量比如TAOTOKEN_API_KEY值就是你的 Key。如果你需要调用模型对话接口做测试Base URL 填https://taotoken.net/apiModel ID 根据你选的模型填比如gpt-4o或claude-3-5-sonnet。这三个要素——Base URL、API Key、Model ID——在后面的配置片段里会反复出现先记好。对于纯静态站点来说重定向配置本身不需要 API Key。但如果你打算用 Netlify Functions 做重定向后的数据处理或者用 Edge Functions 做动态跳转判断那就需要把 Key 配到环境变量里。我建议一开始就把环境变量配好后面扩展时不用再折腾。还有一点确认你的 Netlify CLI 已经登录。在终端执行netlify status如果显示未登录先跑netlify login。本地测试重定向规则时netlify dev会模拟边缘节点的行为比直接部署到线上再调试快得多。3. 可复制配置_redirects 与 netlify.toml 完整片段这一节给出可以直接复制的配置片段。我会分三个场景基础 301 跳转、SPA 兜底、以及带条件判断的高级规则。每个片段都标注了文件路径和放置位置。3.1 _redirects 文件基础写法在publish目录下创建_redirects文件没有扩展名。如果你用 Vite路径是public/_redirects构建时会自动复制到dist。内容如下# 旧文章链接永久跳转到新链接 /blog/old-post-1 /blog/new-post-1 301 /blog/old-post-2 /blog/new-post-2 301 # 带通配符的批量跳转 /docs/* /documentation/:splat 301 # 强制 HTTPS 和去掉 www http://example.com/* https://example.com/:splat 301 https://www.example.com/* https://example.com/:splat 301每行格式是「原路径 目标路径 状态码」用空格或 Tab 分隔。#开头是注释。:splat是通配符捕获的内容/docs/guide会跳转到/documentation/guide。3.2 netlify.toml 结构化配置如果你更喜欢把配置集中管理用netlify.toml的[[redirects]]块。在项目根目录的netlify.toml里追加[[redirects]] from /blog/old-post-1 to /blog/new-post-1 status 301 force false [[redirects]] from /docs/* to /documentation/:splat status 301 [[redirects]] from /* to /index.html status 200force false表示如果目标路径存在真实文件就不执行重定向。force true则强制跳转忽略真实文件。SPA 兜底通常用status 200这叫 rewrite浏览器地址栏不变但返回index.html的内容。3.3 SPA 兜底与 404 处理单页应用最怕刷新子路由白屏。在_redirects最后加一行/* /index.html 200这行必须放在所有具体规则之后。如果你同时有 404 页面可以这样写# 具体跳转规则 /old-page /new-page 301 # API 代理如果有 /api/* https://taotoken.net/api/:splat 200 # SPA 兜底 /* /index.html 200注意如果你用了 Netlify 的 404 自定义页面需要在netlify.toml里配[[redirects]] from /* to /404.html status 404但这条和 SPA 兜底冲突二选一。SPA 用 200 rewrite多页站点用 404。3.4 带条件判断的高级规则Netlify 支持基于查询参数、请求头、Cookie 的条件重定向。比如根据语言跳转[[redirects]] from / to /zh/ status 302 conditions {Country [CN]} [[redirects]] from / to /en/ status 302或者根据查询参数/products /products-sale 302 QueryStringon_saletrue这些规则在边缘节点执行延迟极低。但调试时要注意条件不满足时请求会继续往下匹配不会报错。4. 部署后逐条验证状态码与优先级检查配置写完了部署上去不代表就完事了。你需要逐条验证跳转是否按预期执行。我用curl命令来演示你也可以用浏览器开发者工具的 Network 面板。4.1 检查状态码部署完成后打开终端执行curl -I https://your-site.netlify.app/blog/old-post-1看返回的HTTP/2后面的状态码。如果是301说明永久重定向生效。如果是200说明规则没匹配上请求直接返回了原路径的内容。如果是404说明规则写错了或者文件没被读取。对于 SPA 兜底测试一个不存在的路径curl -I https://your-site.netlify.app/some/random/path应该返回200并且Content-Type是text/html。如果返回404说明兜底规则没生效。4.2 验证重定向链有时候一条规则跳转后目标路径又触发了另一条规则形成重定向链。用curl -L跟随跳转看最终落到哪里curl -IL https://your-site.netlify.app/docs/guide输出里会显示每一跳的状态码和Location头。理想情况下只有一跳。如果看到多个 301说明规则有重叠需要优化。4.3 检查优先级Netlify 按规则顺序匹配。你可以故意写两条冲突的规则来测试优先级/test /page-a 301 /test /page-b 301部署后访问/test看跳到/page-a还是/page-b。应该是/page-a因为它在前面。验证完记得删掉测试规则。4.4 用 Netlify 预览部署测试Netlify 的 Deploy Preview 功能可以在不影响生产环境的情况下测试规则。在 GitHub 上开一个 PRNetlify 会自动生成一个预览 URL。在这个 URL 上测试所有重定向规则确认无误后再合并到主分支。4.5 检查 _redirects 是否被读取如果所有规则都不生效先确认文件是否在正确位置。在 Netlify 后台的 Deploys 页面点击最新部署查看「Deploy summary」里的「Redirect rules」。如果显示 0 条规则说明文件没被读取。检查publish目录里是否有_redirects文件以及构建命令是否把它复制过去了。5. 常见报错排查401、local proxy failed、reading choices这一节列出我在实际项目中踩过的坑以及对应的排查思路。5.1 401 Unauthorized如果你在重定向目标里调用了 TaoToken 的 API返回 401说明 API Key 没传对。检查 Netlify 环境变量里TAOTOKEN_API_KEY是否设置正确以及在函数代码里是否用process.env.TAOTOKEN_API_KEY读取。不要在前端代码里硬编码 KeyNetlify 的环境变量只在构建时和函数运行时可用。5.2 local proxy failed用netlify dev本地测试时如果看到local proxy failed通常是代理目标不可达。检查netlify.toml里的代理规则[[redirects]] from /api/* to https://taotoken.net/api/:splat status 200 force true确认to的 URL 可以正常访问。如果目标需要认证确保请求头里带了Authorization: Bearer key。本地测试时netlify dev会启动一个代理服务器如果目标域名解析失败或超时就会报这个错。5.3 reading choices 报错这个报错通常出现在调用模型接口时返回体里没有choices字段。原因可能是请求格式不对或者 Model ID 写错了。检查你的请求体{ model: gpt-4o, messages: [{role: user, content: hello}] }确认 Base URL 是https://taotoken.net/api路径是/v1/chat/completions。如果 Model ID 不存在接口会返回错误信息而不是choices。在 TaoToken 的模型对话页面可以测试可用的 Model ID。5.4 OAuth 相关错误如果你用 Netlify 的 OAuth 功能做访问控制重定向规则可能会和 OAuth 回调冲突。确保 OAuth 回调路径没有被通配规则拦截。比如/* /index.html 200这条规则会把/oauth/callback也 rewrite 到index.html导致 OAuth 流程失败。解决办法是在兜底规则之前加一条/oauth/* /oauth/:splat 200或者把 OAuth 回调路径排除在通配规则之外。5.5 规则不生效的通用排查清单按这个顺序检查第一_redirects文件是否在publish目录里第二文件是否有扩展名不能有第三规则顺序是否把具体规则放在了通配规则前面第四状态码是否写对301/302/200第五netlify.toml和_redirects是否有冲突第六部署日志里是否显示规则被加载。6. 接入与排障资源重定向规则调通之后如果你需要把某些路径代理到 AI 接口或者用 Netlify Functions 做动态跳转判断可以进一步配置。TaoToken 的 API Key 在https://taotoken.net/api-keys创建接入文档在https://taotoken.net/doc可以查到完整的请求格式和错误码说明。对于需要长期跑编码任务或 Agent 的场景Coding Plan 提供了更稳定的调用额度适合把重定向后的请求转发到模型接口做自动化处理。如果你只是想先验证模型是否可用直接在模型对话页面发一条消息就能看到返回结果不用写代码。排障时优先检查 API Keys 页面确认 Key 状态然后对照接入文档里的错误码表定位问题。大部分 401 和 404 都是 Key 没传对或路径写错导致的逐条核对 Base URL、Key、Model ID 这三件套基本能解决。