Cookie 辅助工具

Cookie 辅助工具提供简单的 Cookie 管理接口，方便开发者设置、解析和删除 Cookie。

导入

import { Hono } from 'hono'
import {
  deleteCookie,
  getCookie,
  getSignedCookie,
  setCookie,
  setSignedCookie,
  generateCookie,
  generateSignedCookie,
} from 'hono/cookie'

用法

普通 Cookie

app.get('/cookie', (c) => {
  setCookie(c, 'cookie_name', 'cookie_value')
  const yummyCookie = getCookie(c, 'cookie_name')
  deleteCookie(c, 'cookie_name')
  const allCookies = getCookie(c)
  // ...
})

签名 Cookie

注意：设置和获取签名 Cookie 会返回 Promise，因为创建 HMAC SHA-256 签名所用的 WebCrypto API 是异步的。

app.get('/signed-cookie', (c) => {
  const secret = 'secret' // make sure it's a large enough string to be secure

  await setSignedCookie(c, 'cookie_name0', 'cookie_value', secret)
  const fortuneCookie = await getSignedCookie(
    c,
    secret,
    'cookie_name0'
  )
  deleteCookie(c, 'cookie_name0')
  // `getSignedCookie` will return `false` for a specified cookie if its signature fails verification
  const allSignedCookies = await getSignedCookie(c, secret)
  // ...
})

NOTE

getSignedCookie 区分两种情况：Cookie 含有签名但验证失败时返回 false；Cookie 的签名格式无效时，会被视为根本不是签名 Cookie，并返回 undefined，与 Cookie 不存在时相同。按名称获取单个 Cookie 和获取所有签名 Cookie 时都适用此规则。由于 false 和 undefined 都是假值，if (!value) 可以同时处理这两种情况。

生成 Cookie

generateCookie 和 generateSignedCookie 函数允许直接创建 Cookie 字符串，而不在响应头中设置它们。

generateCookie

// Basic cookie generation
const cookie = generateCookie('delicious_cookie', 'macha')
// Returns: 'delicious_cookie=macha; Path=/'

// Cookie with options
const cookie = generateCookie('delicious_cookie', 'macha', {
  path: '/',
  secure: true,
  httpOnly: true,
  domain: 'example.com',
})

generateSignedCookie

// Basic signed cookie generation
const signedCookie = await generateSignedCookie(
  'delicious_cookie',
  'macha',
  'secret chocolate chips'
)

// Signed cookie with options
const signedCookie = await generateSignedCookie(
  'delicious_cookie',
  'macha',
  'secret chocolate chips',
  {
    path: '/',
    secure: true,
    httpOnly: true,
  }
)

注意：与 setCookie 和 setSignedCookie 不同，这些函数只生成 Cookie 字符串。如果需要在请求头或响应头中设置，必须手动完成。

选项

setCookie & setSignedCookie

• domain: string
• expires: Date
• httpOnly: boolean
• maxAge: number
• path: string
• secure: boolean
• sameSite: 'Strict' | 'Lax' | 'None'
• priority: 'Low' | 'Medium' | 'High'
• prefix: secure | 'host'
• partitioned: boolean

示例：

// Regular cookies
setCookie(c, 'great_cookie', 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
  httpOnly: true,
  maxAge: 1000,
  expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
  sameSite: 'Strict',
})

// Signed cookies
await setSignedCookie(
  c,
  'fortune_cookie',
  'lots-of-money',
  'secret ingredient',
  {
    path: '/',
    secure: true,
    domain: 'example.com',
    httpOnly: true,
    maxAge: 1000,
    expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
    sameSite: 'Strict',
  }
)

deleteCookie

• path: string
• secure: boolean
• domain: string

示例：

deleteCookie(c, 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
})

deleteCookie 返回已删除的值：

const deletedCookie = deleteCookie(c, 'delicious_cookie')

__Secure- 和 __Host- 前缀

Cookie 辅助工具支持 Cookie 名称使用 __Secure- 和 __Host- 前缀。

要验证 Cookie 名称是否具有前缀，请指定 prefix 选项。

const securePrefixCookie = getCookie(c, 'yummy_cookie', 'secure')
const hostPrefixCookie = getCookie(c, 'yummy_cookie', 'host')

const securePrefixSignedCookie = await getSignedCookie(
  c,
  secret,
  'fortune_cookie',
  'secure'
)
const hostPrefixSignedCookie = await getSignedCookie(
  c,
  secret,
  'fortune_cookie',
  'host'
)

同样，设置 Cookie 时若想指定前缀，请为 prefix 选项设置相应的值。

setCookie(c, 'delicious_cookie', 'macha', {
  prefix: 'secure', // or `host`
})

await setSignedCookie(
  c,
  'delicious_cookie',
  'macha',
  'secret choco chips',
  {
    prefix: 'secure', // or `host`
  }
)

遵循最佳实践

新的 Cookie RFC（又称 cookie-bis）和 CHIPS 包含开发者应遵循的 Cookie 设置最佳实践。

• RFC6265bis-13
  • Max-Age/Expires 限制
  • __Host-/__Secure- 前缀限制
• CHIPS-01
  • Partitioned 限制

Hono 遵循这些最佳实践。 在以下情况下，Cookie 辅助工具解析 Cookie 时会抛出 Error：

• Cookie 名称以 __Secure- 开头，但未设置 secure 选项。
• Cookie 名称以 __Host- 开头，但未设置 secure 选项。
• Cookie 名称以 __Host- 开头，但 path 不是 /。
• Cookie 名称以 __Host- 开头，但设置了 domain。
• maxAge 选项的值超过 400 天。
• expires 选项的值晚于当前时间 400 天。