Astro Advanced Routing 怎麼用？用 src/fetch.ts 插入請求管線

先確認專案真的在 Astro 7 路徑#

Advanced Routing 是 [email protected] 加入的功能，src/fetch.ts 在 v7 也成為保留檔名。先查看目前版本與是否已有同名檔案：

1
pnpm list astro --depth 0
2
test -e src/fetch.ts && sed -n '1,220p' src/fetch.ts || true
3
rg -n 'fetchFile|advancedRouting|experimental' astro.config.mjs package.json src

如果專案仍是 Astro 5 或 6，不要只建立檔案就期待它有 v7 的 request pipeline 行為。可以先看 Astro 7 升級前的建置與設定檔清單，把 Node.js、Vite、Markdown plugin、adapter 和現有 src/fetch.ts 用途分開驗證。

最小做法：保留 Astro 內建 pipeline#

多數需求只是加入 request logging、驗證某個 header、或在回應完成後補一個 header。這時使用 FetchState 和 astro()，不要自己重寫所有 handler：

1
import type { Fetchable } from 'astro'
2
import { FetchState, astro } from 'astro/fetch'
3

4
export default {
5
  async fetch(request: Request): Promise<Response> {
6
    const state = new FetchState(request)
7
    const url = new URL(request.url)
8

9
    if (url.pathname.startsWith('/admin/')) {
10
      console.log(`admin request: ${request.method} ${url.pathname}`)
11
    }
12

13
    const response = await astro(state)
14
    response.headers.set('X-Route-Pipeline', 'astro')
15
    return response
16
  },
17
} satisfies Fetchable

這個結構保留 Astro 原本的路由順序，並把自訂邏輯放在 pipeline 前後。若要做登入或權限判斷，console.log 只是一個示範位置；實際上應使用已驗證的 session、token 或 adapter 提供的身份資訊，不要用未驗證的 cookie 字串當成授權結果。

什麼時候要拆開個別 handler#

如果需求是「保留 actions 和 pages，但不要使用某個內建階段」，或「在 middleware 和 pages 中間插入自己的處理」，才需要從 astro/fetch 匯入個別 handler。官方示範的基本形狀如下：

1
import { FetchState, actions, middleware, pages, i18n } from 'astro/fetch'
2

3
export default {
4
  async fetch(request: Request): Promise<Response> {
5
    const state = new FetchState(request)
6

7
    const actionResponse = await actions(state)
8
    if (actionResponse) return actionResponse
9

10
    console.log(`rendering: ${new URL(request.url).pathname}`)
11
    const response = await middleware(state, (nextState) => pages(nextState))
12
    return i18n(state, response)
13
  },
14
}

這種寫法的維護成本比 astro(state) 高，因為你現在要負責記住哪些 handler 被保留、先後順序和 response 是否已被處理。每次升級 Astro 都要重新對照官方 routing 文件，不要把目前看到的 handler 清單當成永久 API 順序。

如果團隊偏好 Hono，也可以從 astro/hono 使用相同概念的 wrapper，把 Hono middleware 和 Astro handlers 放在同一條 pipeline。這是選擇另一個路由組合方式，不代表 Hono 會自動替你處理 Astro 的 session、i18n 或 cache 設定。

src/fetch.ts 衝突時改名或停用#

Astro 7 會自動尋找 src/fetch.ts、src/fetch.js、src/fetch.mjs 或 src/fetch.mts。如果原本就有同名檔案，Astro 可能把它當成 Advanced Routing 入口，造成與原本用途無關的錯誤。

可以在 astro.config.mjs 改用其他檔名：

1
import { defineConfig } from 'astro/config'
2

3
export default defineConfig({
4
  fetchFile: 'handler',
5
})

如果專案不需要這個入口，也可以明確停用：

1
import { defineConfig } from 'astro/config'
2

3
export default defineConfig({
4
  fetchFile: null,
5
})

改名與停用都應該和升級分開驗證。先確認 src/fetch.ts 是否被其他程式碼 import，再跑 pnpm check、pnpm build，最後用專案使用的 adapter 或部署環境測一條真正的 request。

上線前要驗證的不是只有 build#

Advanced Routing 會改變 request-time 的入口，因此至少要測：

1. 一般頁面、動態路由與不存在路徑的回應狀態。
2. trailing slash、redirect、session、actions 和 middleware 是否仍依預期執行。
3. 你新增的前置檢查是否會阻擋靜態資產、健康檢查或 webhook。
4. response header、cache、cookie 和錯誤頁是否仍被 adapter 正確輸出。
5. production build 後的 preview 或 staging request，而不是只在 dev server 點開首頁。

如果只想加一個 header 或記錄 URL，先用 astro(state)。只有測試能證明需要重排 pipeline 時，才把內建 handler 拆開；這樣升級時要追蹤的內部邊界比較少。

結論：從包裝內建流程開始#

Astro Advanced Routing 的實用切入點是 src/fetch.ts 加上 FetchState 與 astro()：先保留 Astro 已經處理好的流程，再把自訂檢查放在前後。當需求真的涉及省略或重排 handler，才使用個別 astro/fetch API；同時把保留檔名衝突、adapter request 和 build 後驗證列入 Astro 7 升級清單。

常見問題#