useCookie函數：管理SSR環境下的Cookie

title: useCookie函數：管理SSR環境下的Cookie
date: 2024/7/13
updated: 2024/7/13
author: cmdragon

excerpt:
摘要：本文詳述了useCookie函數在伺服器端渲染(SSR)中的應用，包括讀寫Cookie、配置選項如maxAge、expires、httpOnly、secure、domain、path及SameSite，並提供了encode、decode、default、watch等高級用法示例，以及如何在API路由中操作Cookie。

categories:

• 前端開發

tags:

• Nuxt3
• SSR
• Cookies
• HTTP
• 安全
• 編程
• 前端

掃描二維碼關註或者微信搜一搜：編程智域 前端至全棧交流與成長

useCookie 是一個在伺服器端渲染（SSR）環境中管理 Cookie 的工具函數。它允許開發者在頁面、組件或插件中讀取和寫入 Cookie。這個函數通過創建一個響應式引用（ref）來管理 Cookie 的值，並自動將 Cookie 的值序列化和反序列化為 JSON 格式，以確保在不同環境（如瀏覽器和伺服器）之間的一致性。

基本用法

useCookie 函數接受兩個參數：

1. name：這是一個字元串，用於標識特定的 Cookie。
2. options：這是一個對象，包含了用於配置 Cookie 的選項。

簡單示例

下麵的示例創建了一個名為counter的cookie。如果該cookie不存在，它將被初始設置為一個隨機值。每當我們更新counter變數時，cookie也會相應地更新。

app.vue

<script setup>
const counter = useCookie('counter')

counter.value = counter.value || Math.round(Math.random() * 1000)
</script>

<template>
  <div>
    <h1>計數器: {{ counter || '-' }}</h1>
    <button @click="counter = null">重置</button>
    <button @click="counter--">減少</button>
    <button @click="counter++">增加</button>
  </div>
</template>

options選項

maxAge / expires

maxAge

• 用途：maxAge 用於指定cookie在客戶端存儲的時間長度（以秒為單位）。
• 優先順序：當 maxAge 和 expires 同時設置時，maxAge 優先。這意味著如果設置了 maxAge，則不會使用 expires。
• 客戶端行為：如果設置了 maxAge，cookie將在伺服器設置的時間後過期，即使瀏覽器關閉也會保留。
• 示例：Set-Cookie: mycookie=123; max-age=3600;

expires

• 用途：expires 用於指定cookie的過期時間，它是一個特定的日期和時間，格式為 Wdy, DD-Mon-YYYY HH:MM:SS GMT。
• 客戶端行為：如果設置了 expires，cookie將在這個日期和時間後過期，無論瀏覽器是否關閉。
• 示例：Set-Cookie: mycookie=123; expires=Thu, 01 Dec 2023 12:00:00 GMT;

同時設置 maxAge 和 expires

• 規範：根據cookie存儲模型規範，如果同時設置了 maxAge 和 expires，則 maxAge 應該優先。
• 相容性：儘管規範如此，但並非所有客戶端都會嚴格遵循這一規定。因此，如果需要確保cookie的過期行為一致，應該在伺服器端只設置一個。
• 示例：如果需要同時設置，確保它們指向相同的日期和時間。

預設行為

• 無設置：如果沒有設置 maxAge 和 expires，cookie將僅在會話期間存在，這意味著一旦用戶關閉瀏覽器，cookie將被刪除。

實際應用

在實際應用中，通常建議只使用 maxAge 或 expires 中的一個，以避免潛在的不一致性和相容性問題。如果需要cookie在用戶關閉瀏覽器後仍然存在，可以使用 maxAge。如果需要cookie在特定日期和時間後過期，則使用 expires。

以下是一個使用 maxAge 和 expires 的示例：

// 使用 maxAge
res.setHeader('Set-Cookie', 'mycookie=123; max-age=3600;');

// 使用 expires
res.setHeader('Set-Cookie', 'mycookie=123; expires=Thu, 01 Dec 2023 12:00:00 GMT;');

httpOnly

httpOnly 是一個用於設置cookie屬性的布爾值，它的主要目的是增強Web應用程式的安全性。

httpOnly 屬性的用途

• 用途：當 httpOnly 設置為 true 時，它會指示瀏覽器不允許通過JavaScript的 document.cookie API訪問該cookie。這意味著，即使cookie存儲在用戶的瀏覽器中，也無法通過客戶端腳本（如JavaScript）讀取它。
• 安全性：這個屬性可以防止跨站腳本攻擊（XSS），因為即使攻擊者通過腳本註入攻擊控制了用戶的會話，他們也無法通過腳本獲取到設置了 httpOnly 的cookie。

設置 httpOnly

• 值：httpOnly 可以是 true 或 false。如果是 true，則設置HttpOnly屬性；如果是 false 或未設置，則不設置HttpOnly屬性。
• 預設值：預設情況下，httpOnly 屬性是不設置的。

實際應用

在實際應用中，建議對所有涉及身份驗證、敏感信息的cookie設置 httpOnly 屬性。例如，對於存儲用戶會話ID的cookie，應該始終設置 httpOnly。

以下是如何在設置cookie時使用 httpOnly 屬性的示例：

// 設置 httpOnly 為 true
res.setHeader('Set-Cookie', 'sessionToken=abc123; httpOnly;');

// 在某些伺服器框架中，可能需要這樣設置
// res.cookie('sessionToken', 'abc123', { httpOnly: true });

註意事項

• 當 httpOnly 設置為 true 時，請確保您的JavaScript代碼中不要嘗試通過 document.cookie 訪問該cookie，因為這會導致錯誤。
• 由於 httpOnly cookie不能通過客戶端腳本訪問，因此如果您需要在客戶端腳本中使用這些cookie（例如，用於客戶端邏輯或顯示），則需要考慮其他方法來安全地傳輸所需的信息。

通過使用 httpOnly，您可以顯著提高應用程式的安全性，減少XSS攻擊的風險。

secure

secure 是另一個用於設置cookie屬性的布爾值，它的目的是確保cookie僅通過安全的HTTPS連接發送到伺服器。下麵是關於 secure 屬性的詳細信息：

secure 屬性的用途

• 用途：當 secure 設置為 true 時，cookie將只通過HTTPS連接發送。這意味著如果瀏覽器嘗試通過不安全的HTTP連接發送設置了 secure 屬性的cookie，瀏覽器會忽略這個cookie，並且不會將其發送到伺服器。
• 安全性：這個屬性有助於防止中間人攻擊，因為它確保了cookie在客戶端和伺服器之間傳輸時的加密。

設置 secure

• 值：secure 可以是 true 或 false。如果是 true，則設置Secure屬性；如果是 false 或未設置，則不設置Secure屬性。
• 預設值：預設情況下，secure 屬性是不設置的。

實際應用

在實際應用中，對於包含敏感信息的cookie，如會話cookie，通常建議設置 secure 屬性為 true。

以下是如何在設置cookie時使用 secure 屬性的示例：

// 設置 secure 為 true
res.setHeader('Set-Cookie', 'sessionToken=abc123; secure;');

註意事項

• HTTPS連接：當 secure 設置為 true 時，如果網站沒有啟用HTTPS，那麼設置了 secure 屬性的cookie不會被髮送到伺服器。這可能導致用戶在瀏覽器中看到“無法連接到伺服器”的錯誤消息，或者在某些情況下，可能導致所謂的“hydration錯誤”，即伺服器無法識別客戶端發送的cookie。
• 混合內容：如果網站中包含一些通過HTTP載入的靜態資源（如圖片、CSS、JavaScript文件），並且設置了 secure 屬性的cookie，那麼這些資源可能會因為瀏覽器嘗試發送安全的cookie而不被正確載入。
• 相容性：大多數現代瀏覽器都支持 secure 屬性，但在某些舊版瀏覽器中可能不支持。

domain

domain 屬性在設置 Set-Cookie 的時候用於指定 cookie 的作用域。這個屬性允許你定義 cookie 可以被哪些子功能變數名稱或頂級域訪問。預設情況下，cookie 只在當前請求的域內有效。

domain 屬性的用途

• 定義作用域：domain 屬性允許你指定 cookie 的作用域，使得 cookie 可以在指定的域及其所有子域下被訪問。
• 跨域共用：通過設置 domain 屬性，可以讓 cookie 跨越多個子域共用，這對於需要在不同子域間共用狀態信息的網站特別有用。

實際應用

以下是如何在設置 cookie 時使用 domain 屬性的示例：

// 設置 domain 為 'example.com'
res.setHeader('Set-Cookie', 'sessionToken=abc123; domain=example.com;');

註意事項

1. 子域相容性：確保所有子域都支持相同的 domain 值。如果不相容，可能會導致 cookie 不被正確設置或訪問。
2. 安全性：設置 domain 為頂級域（如 .example.com）可以增加安全性，因為這限制了 cookie 的訪問範圍。然而，這也會限制了跨子域的 cookie 使用。
3. 瀏覽器相容性：大多數現代瀏覽器都支持 domain 屬性，但在一些舊版瀏覽器中可能不支持。

示例

假設你有一個包含多個子域的網站，例如 www.example.com、sub.example.com 和 api.example.com。如果你想讓一個 cookie 能在所有這些子域下被訪問，你可以設置 domain 為 example.com：

res.setHeader('Set-Cookie', 'sessionToken=abc123; domain=example.com;');

這樣設置後，sessionToken 將在 www.example.com、sub.example.com 和 api.example.com 下都能被訪問。

path

path 屬性在設置 Set-Cookie 的時候用於指定 cookie 的有效路徑。這個屬性允許你定義 cookie 可以被哪些路徑下的請求訪問。預設情況下，路徑被設置為當前請求的路徑。

path 屬性的用途

• 定義有效路徑：path 屬性允許你指定 cookie 的有效路徑，使得 cookie 只能在指定的路徑及其子路徑下被訪問。
• 路徑限制：通過設置 path 屬性，可以限制 cookie 的使用範圍，從而提高安全性。

實際應用

以下是如何在設置 cookie 時使用 path 屬性的示例：

// 設置 path 為 '/admin'
res.setHeader('Set-Cookie', 'sessionToken=abc123; path=/admin;');

註意事項

1. 路徑匹配：路徑是首碼匹配的，所以設置 path=/admin 意味著 cookie 在 /admin、/admin/settings 等路徑下都有效。
2. 預設路徑：如果沒有指定 path 屬性，預設路徑是當前請求的路徑。例如，如果請求的路徑是 /user/profile，那麼預設路徑就是 /user/profile。
3. 安全性：通過設置 path 屬性，可以限制 cookie 的使用範圍，從而提高安全性。例如，將 cookie 限制在 /admin 路徑下，可以防止它在其他非管理區域被訪問。

示例

假設你有一個網站，其中 /admin 路徑下的內容需要特殊的 cookie 來驗證用戶許可權。你可以設置 path 為 /admin：

res.setHeader('Set-Cookie', 'adminToken=xyz789; path=/admin;');

這樣設置後，adminToken 只能在 /admin 及其子路徑（如 /admin/settings）下被訪問。

SameSite

encode和decode

default

watch

示例1：

示例2：

API路由中的Cookies

餘下文章內容請點擊跳轉至 個人博客頁面 或者 掃碼關註或者微信搜一搜：編程智域 前端至全棧交流與成長，閱讀完整的文章：useCookie函數：管理SSR環境下的Cookie | cmdragon's Blog

往期文章歸檔：

• 輕鬆掌握useAsyncData獲取非同步數據 | cmdragon's Blog
• 使用 useAppConfig ：輕鬆管理應用配置 | cmdragon's Blog
• Nuxt框架中內置組件詳解及使用指南（五） | cmdragon's Blog
• Nuxt框架中內置組件詳解及使用指南（四） | cmdragon's Blog
• Nuxt框架中內置組件詳解及使用指南（三） | cmdragon's Blog
• Nuxt框架中內置組件詳解及使用指南（二） | cmdragon's Blog
• Nuxt框架中內置組件詳解及使用指南（一） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（十一） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（十） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（九） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（八） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（七） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（六） | cmdragon's Blog
• Nuxt3 的生命周期和鉤子函數（五） | cmdragon's Blog