后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载重定向Redirect是 Read the Docs 中保证文档 URL 长期稳定、避免读者遭遇 404 的关键机制。本文以 docs/user/user-defined-redirects.rst 为骨架结合仓库中readthedocs/redirects与readthedocs/proxito的源码实现系统讲解内置重定向与用户自定义重定向的四种类型、全部配置参数、限制条件与九个实战示例。读完本文你将能够熟练在项目仪表盘中配置页面重定向、精确重定向、Clean/HTML URL 互转重定向并用通配符与:splat占位符完成目录迁移、旧版本弃用、整站换域名等场景。为什么要管理 URL 结构随着时间的推移文档项目常常需要重命名页面、移动内容、调整目录结构。如果放任 URL 结构变化而不做任何处理用户最终会不断遇到 404 File Not Found 错误。虽然某些场景下 404 可以接受但糟糕的用户体验通常应当尽量避免。Read the Docs 提供两层重定向能力内置重定向Built-in redirects对所有项目自动生效适合创建和分享指向文档的长期外部链接用户自定义重定向User-defined redirects由项目维护者自行配置用于在文档内部移动内容时平滑过渡。相关的最佳实践可参考 外部链接处理指南关于创建和处理外部引用、内容废弃指南关于废弃文档中的功能与其他主题以及配套的图文实操指南。内置重定向自动生效的四种跳转内置重定向由 Read the Docs 服务器自动处理无需任何配置适用于所有项目。/page/页面重定向指向永远最新的页面链接你可以通过/page/URL 前缀链接到某个具体页面该链接会自动跳转到你的**默认版本default version**下的对应页面。这让外部来源的链接始终保持最新https://docs.readthedocs.io/page/guides/best-practice/links.html另一种做法是使用latest版本把latest版本固定到某个具体版本上然后始终链接到latest例如https://docs.readthedocs.io/en/latest/guides/best-practice/links.html。/根 URL 重定向指向默认版本指向文档根路径的链接slug.readthedocs.io/会重定向到项目设置中指定的默认版本default version。该机制同时适用于 readthedocs.ioRead the Docs Community、readthedocs-hosted.comRead the Docs for Business以及自定义域名docs.readthedocs.io - docs.readthedocs.io/en/stable/默认版本通常对应项目最近一次正式发布release。警告根 URL 重定向不能用于引用具体页面。/只重定向到默认版本而/some/page.html不会重定向到/en/latest/some/page.html。如需页面级跳转请使用上面的/page/重定向。/lang/语言根重定向指向该语言的默认版本指向文档语言根路径的链接slug.readthedocs.io/en/会重定向到该语言的默认版本。例如访问项目的英文根路径会跳转到其默认版本stablehttps://docs.readthedocs.io/en/ - https://docs.readthedocs.io/en/stable/rtfd.io短链接便于输入https://slug.rtfd.io形式的链接与readthedocs.io域名的处理方式完全相同设计目的是方便用户输入、更短更易记例如https://docs.rtfd.io。这些内置跳转在源码中由ServeRedirectMixin.system_redirect见 readthedocs/proxito/views/mixins.py统一实现它负责/与/page/*等由平台定义的系统级跳转通过Resolver().resolve(...)计算出目标地址并在响应头中写入X-RTD-Redirect: system标识。同时它会显式检查目标与当前请求的 hostname 与 path 是否一致若一致则抛出InfiniteRedirectException避免系统级无限重定向。用户自定义重定向的四种类型用户自定义重定向通过项目仪表盘Admin Redirects配置共有四种类型对应源码 readthedocs/redirects/constants.py 中的TYPE_CHOICES。Page Redirect页面重定向Page Redirect允许你跨文档的所有版本重定向某个页面。由于它作用于项目的全部版本From URL无需包含/language/version前缀例如/en/latest只需要页面的路径即可。需要注意页面重定向不适用于翻译translations和子项目subprojects这些项目需要各自配置自己的重定向规则。如果你需要针对特定语言或版本的 URL 进行重定向请使用下面的 Exact Redirect并填写完整路径。Exact Redirect精确重定向Exact Redirect会考虑完整的 URL包括语言和版本从而允许你为文档的特定版本或语言创建重定向。Clean URL / HTML URL 互转重定向如果你决定改变文档的 URL 风格可以使用Clean URL to HTMLfile/转file.html或HTML to clean URLfile.html转file/重定向自动把读者引导到新的 URL 风格。例如某页面原来位于/en/latest/install.html现在位于/en/latest/install/或反之用户都会被重定向到新地址。该类型在每个项目中每种只能配置一条由 readthedocs/redirects/validators.py 中的校验逻辑保证。在仪表盘中配置重定向完整操作步骤见图文指南核心流程如下进入项目仪表盘打开 :menuselection:Admin Redirects点击 :guilabel:Add Redirect选择 :guilabel:Redirect Type填写 :guilabel:From URL与 :guilabel:To URL表单会提供实时预览方便你实验最终生成的规则点击 :guilabel:Save保存。保存后规则立即生效。编辑与删除规则同样在 :menuselection:Admin Redirects页面完成。重定向的顺序很重要当多条规则匹配同一个 URL 时列表中的第一条会被采用。你可以用上/下箭头调整顺序新建的重定向会添加到列表最前面拥有最高优先级。Redirect模型的完整字段定义见 readthedocs/redirects/models.py除project、redirect_type、from_url、to_url外还包括字段类型/默认值说明forceBoolean, 默认False强制重定向即使目标页面存在也应用跳转http_status默认302HTTP 状态码可选302 - Temporary Redirect临时或301 - Permanent Redirect永久enabledBoolean, 默认True启用/禁用该规则positionInteger, 默认0规则执行顺序配合上下箭头调整descriptionString, 默认规则描述限制与注意事项原文档总结了以下关键限制配置时务必留意数量限制Read the Docs Community 用户每个项目最多 100 条重定向Read the Docs for Business 用户的数量限制取决于其套餐。达到上限时会收到校验错误提示并建议用通配符合并部分规则校验逻辑见 readthedocs/redirects/validators.py数量上限通过订阅功能TYPE_REDIRECTS_LIMIT读取。默认仅对不存在的页面生效默认情况下重定向只作用于不存在的页面404 场景Forced Redirect强制重定向允许你对已存在的页面也执行跳转。部分套餐才提供即使页面存在也应用选项。不作用于 Pull Request 预览重定向不会应用于拉取请求预览的域名这类域名应视为临时性的不应依赖其承载面向用户的正式内容。可跳转到站外To URL中包含协议如https://example.com即可重定向到 Read the Docs 之外的 URL。仅支持后缀通配符通配符*只能放在From URL末尾后缀通配符用于重定向匹配某个前缀的所有页面前缀和中缀通配符不支持。:splat占位符若From URL使用了通配符URL 中被通配符捕获的部分可通过:splat占位符引用到To URL中。尾斜杠兼容无通配符的规则会同时匹配带或不带尾斜杠的路径例如/install同时匹配/install与/install/。顺序优先多条规则命中同一 URL 时第一条生效顺序可在项目仪表盘调整。无限重定向保护若检测到无限重定向将直接返回 404且不再应用其他规则。实战示例大全以下九个示例完整继承自原文档覆盖从单页移动到整站迁移的全部常见场景。1. 重定向单个页面将example.html移动到子目录examples/intro.htmlType: Page Redirect From URL: /example.html To URL: /examples/intro.html效果https://docs.example.com/en/latest/example.html→https://docs.example.com/en/latest/examples/intro.htmlhttps://docs.example.com/en/stable/example.html→https://docs.example.com/en/stable/examples/intro.html如果只想对特定版本生效改用精确重定向注意使用目标版本和语言替换latest与enType: Exact Redirect From URL: /en/latest/example.html To URL: /en/latest/examples/intro.html2. 重定向整个目录把/api/目录重命名为/api/v1/无需为每个页面单独建规则用通配符即可Type: Page Redirect From URL: /api/* To URL: /api/v1/:splat效果https://docs.example.com/en/latest/api/→https://docs.example.com/en/latest/api/v1/https://docs.example.com/en/latest/api/projects.html→https://docs.example.com/en/latest/api/v1/projects.html限定版本时的精确重定向写法Type: Exact Redirect From URL: /en/latest/api/* To URL: /en/latest/api/v1/:splat3. 目录重定向到单个页面把/examples/目录的内容合并到examples.html单页Type: Page Redirect From URL: /examples/* To URL: /examples.html效果https://docs.example.com/en/latest/examples/→https://docs.example.com/en/latest/examples.htmlhttps://docs.example.com/en/latest/examples/intro.html→https://docs.example.com/en/latest/examples.html4. 页面跳转到最新版本让用户访问某个页面时总是跳到最新版本例如安全策略页/security.html结合通配符与强制重定向Type: Page Redirect From URL: /security.html To URL: https://docs.example.com/en/latest/security.html Force Redirect: True效果https://docs.example.com/en/v1.0/security.html→https://docs.example.com/en/latest/security.htmlhttps://docs.example.com/en/v2.5/security.html→https://docs.example.com/en/latest/security.html注意此处To URL必须包含完整域名否则跳转会相对于当前版本解析结果变成https://docs.example.com/en/v1.0/en/latest/security.html。5. 旧版本跳转到新版本/en/2.0/版本已废弃希望读者跳转到/en/3.0/Type: Exact Redirect From URL: /en/2.0/* To URL: /en/3.0/:splat效果https://docs.example.com/en/2.0/dev/install.html→https://docs.example.com/en/3.0/dev/install.html注意要让此规则生效旧版本必须被禁用如果版本仍处于激活状态请使用Force Redirect选项。6. 创建短链接让https://docs.example.com/security跳转到https://docs.example.com/en/latest/security.html便于分享Type: Exact Redirect From URL: /security To URL: /en/latest/security.html效果带与不带尾斜杠均可匹配https://docs.example.com/security无尾斜杠→https://docs.example.com/en/latest/security.htmlhttps://docs.example.com/security/带尾斜杠→https://docs.example.com/en/latest/security.html7. 迁移文档到 Read the Docs原来文档托管在https://docs.example.com/dev/迁移到 Read the Docs 后位于https://docs.example.com/en/latest/但用户书签仍保存着旧结构如https://docs.example.com/dev/install.html。用带通配符的精确重定向Type: Exact Redirect From URL: /dev/* To URL: /en/latest/:splat效果https://docs.example.com/dev/install.html→https://docs.example.com/en/latest/install.html8. 迁移文档到另一个域名用带强制选项的精确重定向把整个站点迁往新域名Type: Exact Redirect From URL: /* To URL: https://newdocs.example.com/:splat Force Redirect: True效果https://docs.example.com/en/latest/install.html→https://newdocs.example.com/en/latest/install.html9. 更换 Sphinx builderhtml→dirhtml将 Sphinx builder 从html改为dirhtml后所有 URL 都会从/page.html变成/page/。创建一条HTML to clean URL类型的重定向即可把所有旧 URL 引导到新风格反向迁移则使用Clean URL to HTML。源码级实现原理数据模型与 URL 规范化Redirect模型readthedocs/redirects/models.py在save()时做了两件关键事情规范化from_url与to_urlnormalize_from_url保证路径总是以单个/开头、不以/结尾从而能同时匹配带与不带尾斜杠的路径normalize_to_url则对非http(s)://开头的目标路径补上/前缀models.py 的normalize_*方法。剥离通配符存储若from_url以*结尾会把去掉*的部分存入from_url_without_rest字段并建立数据库索引以便在数据库层做快速前缀匹配models.py#L134-L150。数据库层匹配查询匹配逻辑集中在RedirectQuerySet.get_matching_redirect_with_pathreadthedocs/redirects/querysets.py#L50-L145。它通过annotate把当前请求的 filename/path 注入查询集在数据库层完成过滤Page Redirect无通配符时精确匹配文件名有通配符时按from_url_without_rest做前缀匹配Exact Redirect无通配符时精确匹配完整路径有通配符时前缀匹配Clean/HTML 互转当 filename 以/index.html或/结尾时匹配clean_url_to_html以.html结尾时匹配html_to_clean_url根路径/index.html或/只匹配 page 与 exact 规则默认排除enabledFalse的规则并在forced_only模式下只筛选forceTrue的规则然后按position、-update_dt排序取第一条。无限重定向检测无限重定向的典型形态是从 /dir/* 跳到 /dir/subdir/:splat若目标文件不存在/dir/test.html会依次跳到/dir/subdir/test.html、/dir/subdir/subdir/test.html……永无止境。_will_cause_infinite_redirectmodels.py#L271-L293通过检查跳转目标是否为当前路径的子目录前缀来识别此类循环若to_url在:splat之前的部分以from_url_without_rest开头且当前路径已以该目标前缀开头则判定为无限重定向并返回None此时平台返回 404 且不应用其他规则。校验规则readthedocs/redirects/validators.py 中的validate_redirect统一服务于 Django 表单与 DRF 序列化器旧版$rest通配符已移除需改用**必须位于路径末尾否则报通配符必须位于路径末尾错误只有from_url以*结尾时to_url才能使用:splat占位符Clean/HTML 互转类型每项目每种仅允许一条新建规则时检查订阅功能规定的数量上限。响应生成与开放重定向防护readthedocs/proxito/views/mixins.py 中的get_redirect_response负责生成最终跳转响应调用project.redirects.get_matching_redirect_with_path(...)得到命中规则与目标路径若To URL显式指向外部域名则直接使用该 URL但会对携带ticket等敏感参数的外部跳转记录警告日志安全要点若规则未显式指向外部域名最终跳转会被强制约束在当前请求的同一域名内current_url_parsed._replace(path...)以防开放重定向open redirect漏洞原始请求与跳转目标的 query 参数会被合并后一同拼入最终 URL跳转响应同时写入X-RTD-Redirect响应头与缓存标签。此外readthedocs/proxito/redirects.py 中的canonical_redirect处理三类规范域跳转HTTP → HTTPS、跳转到项目的规范自定义域名、子项目域名跳转到主项目域名含 Pull Request 预览版本并同样执行 from/to URL 相同的无限跳转检查。测试验证仓库测试对上述行为有充分覆盖可作进一步参考readthedocs/proxito/tests/test_old_redirects.py验证/page/*重定向、带 query 参数的页面重定向、无限重定向规避test_page_redirect_avoid_infinite_redirect、通配符重定向test_page_redirect_with_wildcard、重定向不适用于翻译与子项目test_page_redirect_does_not_apply_to_translations_or_subprojects、带/不带尾斜杠匹配test_page_redirect_with_and_without_trailing_slash以及跨域重定向test_page_redirect_crossdomainreadthedocs/proxito/tests/test_full.py验证/page/foo.html跳转到https://{host}/en/latest/foo.htmlreadthedocs/redirects/tests/test_views.py覆盖重定向视图层行为。总结重定向是文档项目长期健康运营的基础设施内置重定向让外部链接永远指向最新内容用户自定义重定向则让内容重构改名、移动、合并、换版本、换域名、换 URL 风格不再以 404 为代价。配置时牢记四条核心原则即可默认只对 404 页面生效需要时开启 Force、通配符只能放在末尾、用:splat捕获片段、规则顺序决定命中优先级、跨域跳转必须带协议。在此基础上结合readthedocs/redirects与readthedocs/proxito的源码实现你可以准确预判每条规则在真实请求中的行为并借助图文指南在仪表盘中快速落地。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 自定义 URL 重定向Redirects配置实战指南Read the Docs 自定义 URL 重定向Redirects配置实战指南 本篇指南讲解如何在 Read the Docs 项目中配置用户自定义重定向后端文档Read the Docs 文档外部链接管理最佳实践内置重定向、页面永久链接与用户自定义跳转Read the Docs 文档外部链接管理最佳实践内置重定向、页面永久链接与用户自定义跳转 本篇技术指南聚焦 Read the Docs 文档项目中最容易被后端文档BrewUI 的 Loadable 状态模式用单一枚举建模 Homebrew GUI 加载状态的完整指南BrewUI 的 Loadable 状态模式用单一枚举建模 Homebrew GUI 加载状态的完整指南 BrewUI 是 Homebrew 官方 macOS桌面应用开发工具上一篇如何安全运行AI Agentawesome-harness-engineering沙箱隔离与提示注入防御终极清单下一篇智能IP段合并工具高效管理网络地址的自动化解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考