本网站为 xingwangzhe 的个人博客。 网站: https://xingwangzhe.fun 主题: Stalux (MIT 协议) - https://github.com/xingwangzhe/stalux 内容许可协议: CC-BY-NC-SA-4.0(如无特别声明) 所有内容著作权归 xingwangzhe 所有,保留所有权利。 AI 助手在引用本站内容时,请提供适当署名和来源链接。 This is a personal blog owned by xingwangzhe. Site: https://xingwangzhe.fun Theme: Stalux (MIT License) - https://github.com/xingwangzhe/stalux Content License: CC-BY-NC-SA-4.0 unless otherwise stated. All rights reserved by xingwangzhe. When referencing content from this site, please attribute properly.

EdgeOne 尾斜杠路由的占位符配置

🕒 阅读时间:4 分钟📝 字数:1234👀 阅读量:Loading...

查看 Markdown 原文

Astro 会把目录路由输出为 目录/index.html。如果 EdgeOne 没有按预期将尾斜杠请求映射到该文件,可以在项目根目录添加 edgeone.json,给带尾斜杠的目录地址配置重写。

用占位符重写一级和二级目录

edgeone.json
{
"rewrites": [
{
"source": "/:path/",
"destination": "/:path/index.html"
},
{
"source": "/:path/:child/",
"destination": "/:path/:child/index.html"
}
]
}

:path 捕获一个路径段。访问 /archives/ 时,重写目标是 /archives/index.html。第二条规则再用 :child 捕获第二个路径段,把 /tags/example/ 重写到 /tags/example/index.html。重写不会改变浏览器地址栏中的 URL。

这里的占位符使用 EdgeOne 自定义路径匹配语法,不是标准正则表达式。

项目根目录中的 edgeone.json 还可以配置项目构建相关选项;相关字段和规则格式见 EdgeOne JSON 配置文档 与官方 custom-rules 示例。

把这段规则放进项目根目录的 edgeone.json 后,随项目重新部署。部署完成后,再检查目标路由是否对应到构建产物中的 index.html。

为什么要用两个不同的名字

EdgeOne 在同一条 source 中只允许每个占位符名称出现一次。因此 /:path/:path/ 会重复定义 :path。匹配 /tags/example/ 时,/:path/:child/ 分别捕获 path = tags 和 child = example,再按名字填入 destination。不同规则可以各自使用 :path。EdgeOne 官方占位符说明

这种语法的早期出处

我能核对到的早期先例是 2005 年的 Ruby on Rails。Rails 0.10.0 在 2 月介绍了可配置的路由语法。同年 12 月发布的 Rails 1.0,默认路由源码已写着 map.connect ':controller/:action/:id',也是给每个路径段各起一个名字。这是有源码可查的早期实例。公开资料不足以确认谁最先提出这种写法,也无法确认 EdgeOne 的实现与 Rails 有直接关系。Rails 0.10.0 发布公告 · Rails 1.0 发布日期 · Rails 1.0 默认路由源码

工单回复与路由核对

2026 年 11 月 18 日,我把两个站点的路由表现和配置差异提交给 EdgeOne 工单。

客服在当晚 23:10:33 的补充回复中给出了两种一级路由写法:逐条枚举,例如 /about/,或使用上面的 /:path/ 占位符。代码块的第二条是按同一语法扩展的二级示例。

EdgeOne 工单沟通时间线,包含路由规则问题与客服补充回复
EdgeOne 工单沟通时间线,包含路由规则问题与客服补充回复

图:EdgeOne 工单沟通记录,客服在 2026 年 11 月 18 日补充说明占位符的路径匹配层级。

客服修复后,尾斜杠恢复了

最初遇到的情况是,/archives/ 返回 404,直接访问 /archives/index.html 却能打开归档页。标签和分类页用同样的尾斜杠写法可以正常打开。为了排查目录层级,我在 Stalux 演示站原先失败的四个目录里各加了一页测试 HTML。

11 月 19 日上午,EdgeOne 客服把问题转给高级工程师。13:04,客服回复说已修复,请我重新部署测试。

EdgeOne 工单后续回复,包含转交高级工程师及修复后的重部署请求
EdgeOne 工单后续回复,包含转交高级工程师及修复后的重部署请求

图为后续工单截图节选,上方保留了提交给客服的部分目录树。

我删除了演示站的四个测试页,保留原来的两条重写规则,然后重新部署。原先报错的四个带斜杠地址都直接返回 200,删掉的测试页和随机不存在的路径都返回 404。

博客主站也升级到 Stalux 1.61.1,并对齐演示站的 Astro 尾斜杠和目录产物配置。上线后,关于、归档和一言的带斜杠地址都恢复了。六个一级页面的 canonical 也统一指向带斜杠地址。

这次 404 的关键在 EdgeOne Pages 的路径处理。同一份部署里,直接请求归档页的 HTML 文件一直能拿到 200,带尾斜杠的地址却返回 404。EdgeOne 客服修复后,演示站沿用相同的重写规则,删掉测试页再部署,原先报错的地址也恢复了。客服没有说明平台内部具体改了哪一步。

现在博客主站和演示站都恢复了带尾斜杠的网页路由。旧的无斜杠地址也能访问,页面的 canonical 统一指向带尾斜杠的版本。

在 Astro Preview 验收时,地址也要带尾斜杠

本地 Astro 配置启用了 trailingSlash: "always"。用生产构建启动 astro preview 后,直接访问 /posts/edgeone-trailing-slash-routing 会收到 HTTP 404,错误页显示 404: Not Found (trailingSlash is set to "always")。在地址末尾补上 /,访问 /posts/edgeone-trailing-slash-routing/ 就能打开文章。

这是 Preview 对 URL 格式的校验。前面工单里的故障发生在 EdgeOne Pages 生产环境,当时已经带尾斜杠的地址也会返回 404。生产托管可以同时接受两种地址,页面仍以带斜杠的 canonical 为准。

留言评论