Cookie 是伺服器與瀏覽器之間攜帶狀態的關鍵機制。JS 透過 `document.cookie` 存取,但 API 原始、易誤用。本文系統整理基礎操作、屬性意義、編碼處理、安全屬性、現代封裝與替代方案。
Cookie 基本結構
name=value; expires=GMTDate; path=/; domain=example.com; Secure; SameSite=Lax
- name=value:必填,皆為字串,需編碼
- expires / max-age:過期時間(GMT 字串 / 秒數),缺省為會話期 Cookie
- path:生效路徑,預設為設定頁面路徑,設 `/` 全站可用
- domain:生效域名,預設為當前主機名,可設父域名(需符合同源策略)
- Secure:僅 HTTPS 傳輸
- SameSite:`Strict`/`Lax`/`None`(跨站請求攜帶策略),現代預設 `Lax`
基礎讀寫封裝
var Cookie = {
set: function(name, value, options) {
options = options || {};
var parts = [encodeURIComponent(name) + '=' + encodeURIComponent(value)];
if (options.days) {
var d = new Date(); d.setTime(d.getTime() + options.days*864e5);
parts.push('expires=' + d.toUTCString());
}
if (options.maxAge) parts.push('max-age=' + options.maxAge);
parts.push('path=' + (options.path || '/'));
if (options.domain) parts.push('domain=' + options.domain);
if (options.secure) parts.push('Secure');
if (options.sameSite) parts.push('SameSite=' + options.sameSite);
document.cookie = parts.join('; ');
},
get: function(name) {
var m = document.cookie.match(new RegExp('(^|; )' + encodeURIComponent(name) + '=([^;]*)'));
return m ? decodeURIComponent(m[1]) : null;
},
remove: function(name, options) {
options = options || {}; options.days = -1;
this.set(name, '', options);
},
all: function() {
var obj = {}, cookies = document.cookie.split('; ');
for (var i=0; i
編碼陷阱與處理
- **必須編碼**:名稱/值含分號、逗號、空格、等號、非 ASCII 字元時
- 使用 `encodeURIComponent` / `decodeURIComponent`(而非 `escape`/`unescape` 已棄用)
- 儲存 JSON 物件:`JSON.stringify` → `encodeURIComponent`,讀取時反向
安全最佳實踐
| 屬性 | 建議設定 | 理由 |
| Secure | true | 防止明文傳輸被竊聽 |
| SameSite | Lax(預設)或 Strict | 防禦 CSRF,`None` 需配合 Secure |
| HttpOnly | **無法由 JS 設定** | 需由伺服器 `Set-Cookie` 標頭設定,防 XSS 竊取 |
| Domain/Path | 最小權限原則 | 避免洩露給不需存取的子域/路徑 |
| Expires/Max-Age | 盡量短、必要時才長期 | 縮小竊取時間窗口 |
常見問題
- **本地檔案 (`file://`) 無法操作 Cookie**:Chrome 安全限制,改用 `https://localhost` 開發
- **4KB 大小限制**:單一 Cookie 超過 4KB 會被忽略,總量每域約 180 個
- **跨域無法讀取**:`document.cookie` 受同源策略限制
- **第三方 Cookie 逐步淘汰**:Chrome 已預設封鎖,改用 Storage Access API、CHIPS、Related Website Sets
現代替代儲存方案
| API | 容量 | 生命週期 | 自動隨請求發送 | 適用場景 |
| localStorage | ~5MB | 永久(手動清除) | 否 | 用戶偏好、快取、離線資料 |
| sessionStorage | ~5MB | 分頁關閉即清除 | 否 | 表單暫存、單次會話狀態 |
| IndexedDB | 數百 MB | 永久 | 否 | 大量結構化資料、離線應用 |
| Cache API | 配額動態 | 可控 | 否 | Service Worker 離線快取 |
| Cookie | 4KB | 可設定 | **是** | **身份認證、CSRF Token、Server-side 需讀取的狀態** |
TypeScript 類型定義
interface CookieOptions {
days?: number; maxAge?: number; path?: string; domain?: string;
secure?: boolean; sameSite?: 'Strict'|'Lax'|'None';
}
interface CookieStore {
set(name:string, value:string, options?:CookieOptions): void;
get(name:string): string|null;
remove(name:string, options?:CookieOptions): void;
all(): Record;
}