Next.jsのproxyでCookieを設定するとき、cookies()とNextResponseのcookiesでは新しい値が届く先が違う

目次

Next.js(App Router)でCookieを扱うAPI

App RouterでCookieを扱うAPIは、次の3つです。

API使える場所できること
cookies()(next/headers)Server Component / Server Function / Route Handler / proxy読み取り、書き込み(場所によって制限あり)
request.cookies(NextRequest)proxy / Route Handlerリクエストに入っているCookieの読み書き
response.cookies(NextResponse)proxy / Route HandlerレスポンスにSet-Cookieを付ける

https://nextjsjp.org/docs/app/api-reference/functions/cookies

cookies() はNext.js 15から非同期になったので、await を付けて呼びます。

import { cookies } from 'next/headers'

const cookieStore = await cookies()
const token = cookieStore.get('token')?.value

使えるメソッドは get / getAll / has / set / delete / toString です。

Server Componentでは読むだけ

cookies().set と .delete が使えるのは、Server FunctionとRoute Handlerの中だけです。
Server Componentの描画中に呼ぶと、次のエラーになります。

Cookies can only be modified in a Server Action or Route Handler.

ストリーミングが始まった後ではレスポンスヘッダーを変えられない、というHTTPの制約によるものです。

実装では、書き込みを許可するかどうかをリクエストストアの phase で判定しています。

export function areCookiesMutableInCurrentPhase(requestStore: RequestStore) {
  return requestStore.phase === 'action'
}

ページの描画用のストアは phase: 'render'(request-store.ts#L200)で作られるので、書き込みは拒否されます。Route Handler用のストアは phase: 'action'(request-store.ts#L221-L231)なので、書き込めます。

proxyでもcookies()は使える

Next.js 16で、middlewareはproxyに名前が変わりました。公式ドキュメントで cookies() を使える場所として挙げられているのはServer Component、Server Function、Route Handlerで、proxyは載っていません

それでも、実装上はproxyでも cookies() が使え、set も通ります。

proxyを実行する adapter.ts が、ハンドラーを呼ぶ前に createRequestStoreForAPI でリクエストストアを作っているためです。このストアはRoute Handlerと同じ phase: 'action' になります。

const onUpdateCookies = (cookies: Array<string>) => {
  cookiesFromResponse = cookies
}
// ...
const requestStore = createRequestStoreForAPI(
  request,
  request.nextUrl,
  implicitTags,
  onUpdateCookies,
  // ...
)

つまりproxyでは、Cookieを書く方法が cookies().set と response.cookies.set の2つあります。

問題は、この2つで新しい値が届く先が違うことです。

proxyで設定したCookieは、同じリクエストのどこに届くか

1回のリクエストの中で、proxyと、その後のページ描画やRoute Handlerは別々に動きます。ページやRoute Handlerの cookies() が読むのは、基本的にはブラウザが送ってきたCookieヘッダーです。

proxyが返すSet-Cookieは「ブラウザに保存して」という指示なので、ブラウザに届くのはレスポンスを返した後になります。

proxyで設定した値を同じリクエストの中で使えるようにするには、ルーターがproxyのレスポンスを受け取った時点で、後続の処理向けのリクエストに値を移す必要があります。

proxyで設定したCookieの流れ ブラウザ proxy ルーター ページ描画 Server Component Route Handler Cookie: token=old × Set-Cookie: token=new(レスポンス) set-cookie:ブラウザに保存される。new が見えるのは次のリクエストから x-middleware-set-cookie:同じリクエストのページ描画の cookies() に合流 Route Handler は x-middleware-set-cookie を読まない ※ x-middleware-set-cookie が付くのは response.cookies.set を使ったときだけ

検証結果

ブラウザ側のCookieを token=old にしてリクエストを送り、proxyで token=new を設定したときに、それぞれの場所で token の値がどう見えるかを調べました。

proxyでの設定方法ブラウザページの cookies()Route Handlerの cookies()Route Handlerの request.cookies
response.cookies.setnewnewoldold
cookies().setnewoldoldold

検証環境は Next.js 16.4.6 で、next build → next start(Node.jsランタイム)で動かし、curl でリクエストを送りました。

検証に使ったコード

// proxy.js
import { NextResponse } from 'next/server'
import { cookies } from 'next/headers'

export async function proxy(req) {
  const mode = req.nextUrl.searchParams.get('m')
  if (mode === 'fn') {
    ;(await cookies()).set('token', 'new')
    return NextResponse.next()
  }
  const res = NextResponse.next()
  res.cookies.set('token', 'new')
  return res
}
// app/p/page.js
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'

export default async function Page() {
  const c = await cookies()
  return <div>{'PAGE:' + c.get('token')?.value}</div>
}
// app/api/a/route.js
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'

export async function GET(req) {
  const c = await cookies()
  return Response.json({
    cookiesFn: c.get('token')?.value,
    reqCookies: req.cookies.get('token')?.value,
  })
}
curl -s -D - -H 'Cookie: token=old' 'localhost:3000/api/a?m=fn'
curl -s -H 'Cookie: token=old' 'localhost:3000/p?m=fn'

response.cookies.setだけがページに届く理由

違いを生んでいるのは、x-middleware-set-cookie という内部用のヘッダーです。

response.cookies.setはページ向けのヘッダーも書く

NextResponse の cookies.set / delete を呼ぶと、Set-Cookieに加えて x-middleware-set-cookie ヘッダーも書き込まれます。

if (result instanceof ResponseCookies) {
  headers.set(
    'x-middleware-set-cookie',
    result
      .getAll()
      .map((cookie) => stringifyCookie(cookie))
      .join(',')
  )
}

ルーターはproxyのレスポンスにこのヘッダーを見つけると、ブラウザへのレスポンスには載せず、後続の処理に渡すリクエストのヘッダーにだけ移します。

// for set-cookie, the header shouldn't be added to the response
// as it's only needed for the request to the middleware function.
if (key === 'x-middleware-set-cookie') {
  req.headers[key] = value
  continue
}

ページ描画のリクエストストアは、cookies を初めて読むときに mergeMiddlewareCookies を呼び、このヘッダーの値を元のCookieの上に書き込みます。そのため、ページの cookies() では new が見えます。

cookies().setはブラウザ向けのSet-Cookieしか書かない

proxyの中で cookies().set を呼ぶと、変更内容は onUpdateCookies を通じて cookiesFromResponse に溜まります(request-cookies.ts#L116-L148)。最後に adapter.ts がそれを set-cookie ヘッダーに書き込みます。

if (response && cookiesFromResponse) {
  response.headers.set('set-cookie', cookiesFromResponse)
}

x-middleware-set-cookie は書かれないので、ページ描画のCookieはブラウザから届いた old のままです。

これで困るのは、proxyで期限切れのアクセストークンを更新し、ページ側でそのトークンを使ってAPIを呼ぶ、という典型的なパターンです。cookies().set で更新すると、最初のリクエストだけ古いトークンでAPIを呼んでしまいます。

Route Handlerにはどちらの方法でも届かない

検証結果のとおり、Route Handlerでは response.cookies.set を使っても old のままでした。

mergeMiddlewareCookiesがHeadersオブジェクトを読めない

Route Handler用のリクエストストアは、NextRequest を渡して作られます(app-route/module.ts#L894-L901)。この場合、ヘッダーはWeb標準の Headers オブジェクトになります。

一方、mergeMiddlewareCookies は in 演算子と角括弧でヘッダーを読んでいます。これはNode.jsのプレーンなヘッダーオブジェクトにしか効かない読み方です。ソースにも、その旨のTODOコメントがあります。

// TODO: this only fires for `IncomingHttpHeaders`; `Headers` instances
// silently fall through (the `in` check and bracket access don't reach header
// values stored in internal slots). Confirm whether edge / Web `Headers`
// callers need this merge or already handle it elsewhere.
if (
  'x-middleware-set-cookie' in headers &&
  typeof headers['x-middleware-set-cookie'] === 'string'
) {

request.cookies のほうは、元々Cookieヘッダーを読むだけでマージ処理を通らないので、こちらも old です。

Route Handlerにも新しい値を届ける方法

proxyで request.cookies を書き換え、そのヘッダーを NextResponse.next({ request: { headers } }) で後続に渡します。ブラウザに保存させるために、response.cookies.set も合わせて行います。

// proxy.js
import { NextResponse } from 'next/server'

export async function proxy(req) {
  // 後続の処理(ページ・Route Handler)向け
  req.cookies.set('token', 'new')
  const res = NextResponse.next({ request: { headers: req.headers } })

  // ブラウザ向け
  res.cookies.set('token', 'new')
  return res
}

この方法で、ページ・Route Handlerの cookies()・Route Handlerの request.cookies のすべてで new が見えることを確認しました。

これは x-middleware-set-cookie とは別の仕組みです。NextResponse.next({ request }) に渡したヘッダーは x-middleware-request-* と x-middleware-override-headers に変換され(response.ts#L21-L28)、ルーターがリクエストヘッダーそのものを差し替えます(resolve-routes.ts#L668-L697)。Cookieヘッダー自体が token=new になるので、どこで読んでも新しい値になります。

cookies()とresponse.cookiesを混ぜるとSet-Cookieが消える

前の節で見た adapter.ts の処理は、append ではなく headers.set('set-cookie', ...) です。そのため、同じproxyの中で両方を使うと、response.cookies.set で付けたSet-Cookieが上書きされて消えます。

export async function proxy(req) {
  ;(await cookies()).set('a', '1')
  const res = NextResponse.next()
  res.cookies.set('b', '2') // ブラウザに届かない
  return res
}

実際に試したところ、レスポンスに含まれていたのは set-cookie: a=1; Path=/ だけでした。

混ぜたときのSet-Cookieの上書き proxyの戻り値 set-cookie: b=2 (response.cookies.set) adapter.ts headers.set(‘set-cookie’, cookiesFromResponse) 中身は cookies().set の a=1 ブラウザに届く set-cookie: a=1 b=2 は消える append ではなく set なので、既存の set-cookie ヘッダーが置き換わる

proxyの中では、どちらか一方に統一してください。

クライアント側でしか使わないなら、proxyでcookies()を使っても問題ない

proxyで設定したCookieを、ブラウザのJS(document.cookie など)でしか使わないなら、cookies().set でも問題ありません。どちらの方法でもブラウザにはSet-Cookieが届くからです。複数のCookieを設定した場合や、expires を付けた場合も、正しく届くことを確認しました。

set-cookie: a=1; Path=/; Expires=Tue, 01 Jan 2030 00:00:00 GMT
set-cookie: b=2; Path=/

ブラウザは、レスポンスヘッダーを受け取った時点でSet-Cookieを保存します。ページのJSが動くのはその後なので、document.cookie では最初のリクエストから新しい値が読めます。古い値が見えてしまうのは、サーバー側で動く cookies() だけです。

ただし、次の2点には注意してください。

  • 同じproxyの中で response.cookies.set と混ぜないこと
  • httpOnly: true を付けないこと(付けると document.cookie から読めなくなる)

proxyで設定した値を、同じリクエストのサーバー側でも使うかどうかで、使う方法は次のように分かれます。

新しい値を使う場所proxyで使う方法
ブラウザ(クライアントJS)だけcookies().set / response.cookies.set のどちらでもよい
ページ(Server Component)でも使うresponse.cookies.set
Route Handlerでも使うrequest.cookies.set + NextResponse.next({ request: { headers } }) + response.cookies.set

本記事のコード引用・行番号はすべて Next.js v16.4.6 のソースに基づきます。内部実装に依存する挙動なので、バージョンアップで変わる可能性があります。

目次