Astro Cloudflare 為什麼有 SESSION KV？用 session: false 關掉不需要的狀態

SESSION 是哪裡來的#

Astro Sessions 用來在不同 request 之間保存使用者資料，例如偏好、購物車或登入相關狀態。Cloudflare adapter 會替這個功能接上 Workers KV；預設 binding 名稱為 SESSION，部署時可由 Wrangler 自動 provision，也可以在 wrangler.jsonc 手動宣告。

這和「網站是不是放在 Cloudflare」不是同一個判斷。Astro 官方 adapter 文件指出，若只是把 Astro 當成靜態網站產生器，不需要 adapter；只有要部署 on-demand rendering、server islands、Actions 或 Sessions 等 server 功能時，才需要對應的 adapter。可以先用這個命令確認專案實際是否引用 session：

1
rg -n 'Astro\.session|session\.|sessionDrivers|actions|output:|@astrojs/cloudflare' \
2
  astro.config.mjs src package.json wrangler.jsonc

搜尋結果不能單獨證明 runtime 沒有狀態，但能先把「真的使用 session」和「adapter 預設接線」分開。若只是想把網站部署到 Cloudflare 的 static assets，應先檢查是否能移除 adapter，而不是只把 KV 名稱改掉。

純靜態或無 session 網站設定 session: false#

Astro 7.2.0 起，Sessions 可以在全域設定中關閉。false 不只是忽略某個 API，而是讓 session runtime 不進 SSR bundle，adapter 也跳過預設 session driver 的接線：

1
import { defineConfig } from 'astro/config'
2
import cloudflare from '@astrojs/cloudflare'
3

4
export default defineConfig({
5
  output: 'server',
6
  session: false,
7
  adapter: cloudflare(),
8
})

這個範例仍保留 output: 'server' 與 Cloudflare adapter，適合「需要 server rendering，但不需要跨 request session」的網站。若專案其實是完整靜態輸出，應另外依 Astro 7 升級與建置清單 檢查 output、integration 與產出路徑，不要把 session: false 誤當成移除 adapter 的替代方案。

設定後要同步檢查兩邊：

1
pnpm check
2
pnpm build
3
rg -n 'SESSION|session|kv_namespaces' dist .astro astro.config.mjs wrangler.jsonc

dist 或 .astro 的實際輸出位置會依 adapter 與 Astro 版本不同；搜尋是用來找出是否仍有 session driver 或 binding 的線索，不應把「搜尋不到字串」當成完整 runtime 測試。若 build 仍報出 Astro.session 相關錯誤，回頭檢查是否有元件或 integration 真的讀取該 API。

確實使用 session 時，保留或改名 binding#

如果頁面會使用 Astro.session?.get()、set() 或 regenerate()，不要為了讓設定檔看起來乾淨就關掉 Sessions。最簡單的做法是接受預設名稱：

1
export default defineConfig({
2
  adapter: cloudflare(),
3
})

如果既有 Wrangler 設定使用另一個 binding 名稱，則要讓 adapter option 和 wrangler.jsonc 完全一致：

1
export default defineConfig({
2
  adapter: cloudflare({
3
    sessionKVBindingName: 'MY_SESSION_BINDING',
4
  }),
5
})

1
{
2
  "kv_namespaces": [
3
    {
4
      "binding": "MY_SESSION_BINDING"
5
    }
6
  ]
7
}

只改 Astro 設定、不改 Wrangler binding，或反過來只改 KV 名稱，都可能讓部署後的 runtime 找不到相同的 binding。這類問題通常不是 build 語法錯誤，而是 Worker 執行時的環境連線錯誤，所以要把本機 build 與實際 preview／部署分開驗證。

用程式搜尋確認是否真的需要 session#

關閉前可用三個層次盤點：

1. 直接搜尋 Astro.session、sessionDrivers 與自訂 middleware，確認頁面或 endpoint 是否讀寫狀態。
2. 檢查 adapter、integration 與 server islands 是否依賴 Sessions；不要只看 src/pages。
3. 用測試或手動請求驗證登入、購物車、偏好設定等跨 request 行為是否存在。

若只找到文件、型別或未使用的舊元件，可以先移除死程式碼，再設定 session: false。若網站依賴 cookie 來保存小型非敏感 UI 狀態，也不代表一定要使用 Astro Sessions；但驗證時要分清楚 cookie、KV session 與 Cloudflare binding 是三種不同的資料邊界。

最後用部署邊界驗證，而不是只看 build#

完成設定後，至少記錄以下結果：

• pnpm check 與 pnpm build 通過。
• 專案中沒有仍會執行的 Astro.session 呼叫，或已確認它們保留並使用正確 binding。
• session: false 的專案不會把 session 當成必要 runtime；保留 Sessions 的專案則在 Wrangler 設定中有相同的 KV binding 名稱。
• preview 與正式 Worker 的登入、跨 request 資料與錯誤處理符合預期。

如果只是為了消除一個 SESSION 設定提示，先不要直接刪掉 KV。先確認是否是 adapter 的預設行為、是否是既有 session 功能，並把這次變更和 Cloudflare 的部署設定一起 review，才能避免「build 乾淨、上線後狀態遺失」的回歸。

常見問題#