把 EmDash 挂到子路径之前:我们把 /field-notes 下的地址一个个点了一遍

在 Astro 里设置 base 之后,哪些地址会跟着移动,哪些不会;以及上线前值得手动检查的几个地方。

想把站点放在 example.com/field-notes/ 下面,而不是独占一个域名,这是个很常见的要求:主站是别的系统,博客只是挂在下面的一块。

Astro 里对应的配置只有一行 base。所以我们本来以为这篇指南会很短。

结果我们新建了一个博客模板站,设上 base: "/field-notes",构建,启动,然后拿 curl 把每个地址点了一遍。一行配置之外的事,比我们预想的多。下面是实际看到的东西。

测试环境:EmDash 1.4.0,Node 适配器,SQLite,官方博客模板,并且用 emdash seed 灌进了模板自带的 8 篇文章。

export default defineConfig({
  output: "server",
  base: "/field-notes",
  // ...
});

哪些地址跟着 base 走了?

先看好消息。页面本身没问题:

地址结果
/field-notes/200
/field-notes/posts200
/field-notes/rss.xml200
/field-notes/robots.txt200

哪些地址没有动?

后台和接口留在原地:

地址结果
/_emdash/api/health200
/_emdash/admin302,跳到 /_emdash/admin/setup

也就是说,/_emdash 开头的一切,不会搬进 /field-notes。你前面的路由规则,要同时把 /field-notes/* 和 /_emdash/* 都送到这个应用。只送前者,后台就打不开。

另外两个我们碰到的地址,值得提一下:/field-notes/_emdash/api/health 和 /field-notes/sitemap.xml 都返回 500。它们本来就不是该被访问的地址,但如果你的检查脚本是“把前缀拼上去再试”,会被它们吓一跳。

还有一件让我们意外的事:根路径 / 和 /posts 也返回 200。也就是说,同一份内容有两个入口。如果你不想让搜索引擎看到两份,前面的路由只放行 /field-notes/* 和 /_emdash/*,别的一律拒掉。

页面里的链接,一个都没带前缀

这是我们最没想到的一处。打开 /field-notes/ 的首页,查看源码,里面的链接是这样的:

  • 7 篇文章:/posts/a-weekend-with-a-side-project 之类
  • 4 个标签:/tag/opinion 之类
  • 导航栏:/、/pages/about、/posts
  • 还有 /rss.xml、/search

没有一个带 /field-notes。点进去会离开你的子路径,掉到根路径下。

链接的来源有两处,修起来的地方不一样:

  1. 模板代码里写死的。 比如 src/pages/posts/[slug].astro 里的 href={`/tag/${t.slug}`},还有好几个页面里的 href="/posts"。这类要改成以 import.meta.env.BASE_URL 开头。
  2. 数据库里存着的。 导航栏的三项并不是写在模板里的,而是菜单数据,保存在 _emdash_menu_items 表里,地址就是 /、/pages/about、/posts。只改模板,导航栏纹丝不动,得改菜单本身的地址,或者改种子文件之后重新灌。

这个模板站里的这些写法,是模板自己的选择,不是 base 配置出了问题。我们也没有把整个模板改一遍再验证,所以这里只能告诉你该去哪里找,不能保证改完就全对。

机器读的地址,同样没有前缀

给人看的链接之外,还有三样给机器读的东西,我们也看了:

  • /sitemap.xml 里列出的地址形如 .../sitemap-posts.xml,里面的文章地址形如 .../posts/the-case-for-static,都没有 /field-notes。
  • RSS 里每一篇的 <link> 同样是 .../posts/...。
  • 根路径的 /robots.txt 里有 Disallow: /_emdash/,并且指向了站点地图;而 /field-notes/robots.txt 里只有 User-agent: * 和 Allow: /,既没有屏蔽 /_emdash/,也没有站点地图。

最后一条值得多想一下:搜索引擎只会去域名根路径读 robots.txt。放在子路径下的那份,实际上没有人会读。如果你的主站不是 EmDash,你得自己在主站的 robots.txt 里把 /_emdash/ 屏蔽掉。

站点地图、RSS 里没有前缀,意味着提交给搜索引擎的地址,会是子路径之外的地址。这一点,我们只是看到了现象,没有去追它是哪一行代码决定的。

开发模式会骗你

我们一开始是用 astro dev 测的,结果是这样:

  • /_emdash/api/health 返回 500,日志里是 Cannot read properties of undefined (reading 'registry')。
  • /sitemap.xml 返回 500,内容是 EmDash not configured。

我们以为是 base 把运行时弄坏了。把 base 删掉,两个地址又都回到 200,更加确信了。

直到我们改成先 astro build 再用 node ./dist/server/entry.mjs 启动,上面两个地址在设置了 base 的情况下都是 200。

所以不要用开发模式判断子路径配得对不对。这个差别我们没有查清楚原因。

上线前,我们会手动点这几个地方

  1. 构建、启动,用 curl 看一遍 /field-notes/ 的首页源码,搜一下有没有以 href="/ 开头、却没有 /field-notes 的链接。
  2. 打开 /_emdash/admin,确认前面的路由规则把它送到了应用。
  3. 看一眼 sitemap.xml 和 rss.xml 里的地址。
  4. 在主站的 robots.txt 里确认 /_emdash/ 已经屏蔽。
  5. 访问 / 和 /posts,决定你想不想让它们存在。

我们没有测的

  • 没有把前面的路由规则放到真实的 Cloudflare Worker 或 nginx 上,上面说的“要同时送 /field-notes/* 和 /_emdash/*”,是按观察到的行为推出来的。
  • 没有在 Cloudflare 适配器下试,只试了 Node。
  • 没有改完整个模板里的链接。

如果可以不用子路径,用一个独立的子域名,会省掉这篇文章里的大部分事。