---
title: EdgeOne 尾斜杠路由的占位符配置
tags:
  - edgeone
  - pages
categories:
  - 技术
date: 2026-11-18 21:30:00
updated: 2026-11-19 14:33:06
desc: 记录 EdgeOne Pages 尾斜杠路由的 404、占位符重写规则和平台修复后的复测结果。
abbrlink: edgeone-trailing-slash-routing
---
Astro 会把目录路由输出为 `目录/index.html`。如果 EdgeOne 没有按预期将尾斜杠请求映射到该文件，可以在项目根目录添加 `edgeone.json`，给带尾斜杠的目录地址配置重写。

<!--more-->

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

```json title="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 配置文档](https://makers.edgeone.link/document/edgeone-json) 与[官方 custom-rules 示例](https://github.com/TencentEdgeOne/pages-templates/blob/main/examples/custom-rules/edgeone.json)。

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

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

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

## 这种语法的早期出处

我能核对到的早期先例是 2005 年的 Ruby on Rails。Rails 0.10.0 在 2 月介绍了可配置的路由语法。同年 12 月发布的 Rails 1.0，默认路由源码已写着 `map.connect ':controller/:action/:id'`，也是给每个路径段各起一个名字。这是有源码可查的早期实例。公开资料不足以确认谁最先提出这种写法，也无法确认 EdgeOne 的实现与 Rails 有直接关系。[Rails 0.10.0 发布公告](https://rubyonrails.org/2005/2/24/rails-0-10-0-routing-web-services-components-oracle) · [Rails 1.0 发布日期](https://rubygems.org/gems/rails/versions/1.0.0) · [Rails 1.0 默认路由源码](https://github.com/rails/rails/blob/v1.0.0/railties/configs/routes.rb#L15-L16)

## 工单回复与路由核对

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

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

![EdgeOne 工单沟通时间线，包含路由规则问题与客服补充回复](/images/edgeone-trailing-slash-routing/edgeone-ticket-timeline.webp)

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

## 客服修复后，尾斜杠恢复了

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

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

![EdgeOne 工单后续回复，包含转交高级工程师及修复后的重部署请求](/images/edgeone-trailing-slash-routing/edgeone-ticket-followup.jpg)

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

我删除了演示站的四个测试页，保留原来的两条重写规则，然后重新部署。原先报错的四个带斜杠地址都直接返回 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 为准。


---

**作者：**xingwangzhe

**本文链接：**[https://xingwangzhe.fun/posts/edgeone-trailing-slash-routing/](https://xingwangzhe.fun/posts/edgeone-trailing-slash-routing/)

本文采用[知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://creativecommons.org/licenses/by-nc-sa/4.0/)进行许可。