把 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。
  • 沒有改完整個範本裡的連結。

如果可以不用子路徑,用一個獨立的子網域,會省掉這篇文章裡的大部分事。