Skip to main content
技術

Cloudflare Pages + Better Auth の認証テスト手順｜ローカル開発環境で確認する方法

2026年5月24日 9分で読めます 技術

Cloudflare Pages Functions で Better Auth を実装したあと、ローカル開発環境で認証機能を確認する手順を整理します。wrangler pages dev、get-session、ログイン確認、admin 権限、Network・Console・wrangler ログの見方まで解説します。

#Better Auth #Cloudflare
Cloudflare Pages + Better Auth の認証テスト手順｜ローカル開発環境で確認する方法

はじめに

Cloudflare Pages Functions で Better Auth のような認証機能を実装すると、次に必要になるのが「開発環境でどう確認するか」だ。

前回の記事「Cloudflare Pages + Turso + Better Auth のアーキテクチャ」で実装の全体像を解説したが、今回は開発環境での動作確認に特化する。

ここで曖昧なまま進めると、ログインできない、サインアップに失敗する、admin 画面に入れない、といった問題が起きたときに切り分けが難しくなる。

この記事では、Cloudflare Pages + Better Auth を実装したあとに、開発環境で認証機能をどうテストすればよいかを整理する。

フロントだけでなく、Functions、DB、権限確認まで含めた最小の確認フローを解説する。

まず前提を整理する

認証機能の確認で大事なのは、フロントエンドだけ見ても不十分だということだ。

Cloudflare Pages + Better Auth の場合、少なくとも次の3層がある。

  • フロントエンド画面
  • Pages Functions の認証 API
  • セッションやユーザー情報を保存する DB

そのため、npm run dev で画面だけ開いても、本当に認証が動いているかは分からない。

開発環境で必要な準備

認証機能を確認する前に、最低限これが必要だ。

  • Better Auth の API エンドポイントがある
  • 認証テーブルが DB に作成されている
  • .dev.vars などに DB 接続情報と auth 用 secret がある
  • wrangler pages dev で Functions を含めて起動できる

Windows での開発の場合は、「Windows で Turso マイグレーション：CLI 不要な方法」も合わせて参考にするとよい。

.dev.vars にはローカル用の secret や DB 接続情報を置く。

wrangler.toml には compatibility date や compatibility flags など実行環境の設定を書く。

必要になる環境変数は、だいたい次のようなものだ。

TURSO_DATABASE_URL=libsql://...
TURSO_AUTH_TOKEN=...
BETTER_AUTH_SECRET=...
BETTER_AUTH_URL=http://localhost:8788

Better Auth では、BETTER_AUTH_URL または baseURL を明示しておくのが安全だ。

ローカルでは http://localhost:8788 のように wrangler pages dev の起動ポートと揃える。

ポートを変える場合は .dev.vars 側の BETTER_AUTH_URL も合わせて変更する。

Better Auth は内部で Node.js の AsyncLocalStorage を利用するため、Cloudflare Workers / Pages Functions で使う場合は nodejs_compat または nodejs_als の compatibility flag を確認しておく必要がある。

compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_compat"]

wrangler.toml に設定しておけば、ローカルの wrangler pages dev でも本番に近い条件で確認しやすくなる。

認証機能の確認は pages:dev で行う

認証機能の確認では、基本的に vite dev ではなく wrangler pages dev を使う。

npm run build
npx wrangler pages dev dist --compatibility-date=2026-04-01 --port 8788

あるいは、プロジェクトに pages:dev script があればそれを使っても構わない。

重要なのは、Functions を含めた実行環境で確認することだ。

最初に確認する URL

認証機能を実装したあと、開発環境では次の順で見ると切り分けしやすい。

  1. /login
  2. /api/auth/get-session
  3. admin ルート
  4. 公開ルート

1. /login

まずはログイン画面が開くかを確認する。

ここで見るのは次の点だ。

  • 画面が表示されるか
  • サインインとサインアップの切り替えが動くか
  • フォーム送信時にエラーメッセージが表示されるか

2. /api/auth/get-session

未ログイン状態では、アプリの実装に応じて 200 で null 相当のセッションが返る場合もあれば、401 として扱う場合もある。

重要なのは 500 が出ないことと、未ログイン状態をアプリ側が正しく判定できていることだ。

500 が出る場合は、入力ミスではなくサーバー側の認証処理が落ちている。

3. admin ルート

たとえば /admin/members や /admin/competitions のような admin 画面に直接入ってみる。

確認ポイントは次だ。

  • 未ログインなら /login へリダイレクトされるか
  • ログイン済み member なら拒否されるか
  • admin ロールなら表示できるか

4. 公開ルート

/ や /matches のような公開画面も確認する。

ログイン済み / 未ログインで表示が不自然に崩れていないか、ヘッダー導線や role hint が意図どおりかを見る。

テスト用アカウントの作り方

開発環境では、実在するメールアドレスでなくてもよい構成が多い。メール認証を入れていないなら、形式上メールアドレスとして成立していればサインアップできる。

例:

admin-test@example.com
member-test@example.com

そのうえで、admin 権限が必要な場合は DB で手動付与する。

update "user"
set role = 'admin'
where email = 'admin-test@example.com';

※ テーブル名はプロジェクトの Better Auth 設定に合わせて読み替える。

付与後の確認には次のクエリも使える。

select id, email, role
from "user"
where email in ('admin-test@example.com', 'member-test@example.com');

※ テーブル名はプロジェクトの Better Auth 設定に合わせて読み替える。

この手順を README や運用ドキュメントに書いておくと、毎回迷わずに済む。

ログイン確認で見るべきログ

認証機能の不具合は、ブラウザ画面だけ見ても原因が分からないことが多い。

最低限、次の3つをセットで見る。

ブラウザ Console

フロントエンドの例外や fetch 失敗の兆候が見える。

ただし、拡張機能由来のログが混ざることも多いので、chrome-extension:// などは基本的に無視して構わない。

Network タブ

ここが最重要だ。認証系では次を見る。

  • GET /api/auth/get-session
  • POST /api/auth/sign-up/email
  • POST /api/auth/sign-in/email
  • GET /api/admin/session（admin 判定用に独自実装している場合）

見るべきポイントは、401 / 403 / 500 の違いだ。

  • 401: 未ログイン
  • 403: ログイン済みだが権限不足
  • 500: サーバー側で例外

wrangler pages dev のターミナルログ

Cloudflare Pages Functions の問題は、ここに本当の原因が出る。

たとえば、次のような問題はブラウザ側より wrangler のログの方が分かりやすい。

  • node:async_hooks が見つからない
  • DB 接続失敗
  • env 不足
  • handler 内の例外

よくある詰まりどころ

1. BETTER_AUTH_URL と実際の起動ポートがずれる

8788 で起動する想定だったのに、別ポートで確認していると認証 API の base URL がずれて失敗することがある。

対策:

  • ローカル起動ポートを固定する
  • .dev.vars の BETTER_AUTH_URL を起動ポートに合わせて明示する

2. 500 が出るのに画面上は「失敗しました」しか見えない

UI 側で例外を握りつぶしているパターンだ。

対策:

  • auth client の result.error だけでなく catch も拾う
  • エラーメッセージを画面に出す

3. ログインはできたのに admin に入れない

多くの場合、これは認証ではなく認可の問題だ。

対策:

  • user.role を確認する
  • member と admin の挙動を分けて考える

最小の確認チェックリスト

開発環境で認証機能を確認するときは、次の7点で十分だ。

No

確認項目

期待結果

1

wrangler pages dev で起動

Functions 込みで起動できる

2

/login を開く

ログイン画面が表示される

3

Sign Up

ユーザー作成に成功する

4

/api/auth/get-session

500 にならない・セッション内容を確認できる

5

未ログインで admin ルート

/login にリダイレクト

6

member で admin ルート

403 またはアクセス拒否

7

admin で admin ルート

画面が表示される

この 7 点が通れば、MVP 段階の認証確認としてはかなり十分だ。

まとめ

Cloudflare Pages + Better Auth の認証確認では、画面だけ見ていると原因を見失う。

大事なのは次の3つだ。

  • Functions を含めて wrangler pages dev で確認すること
  • get-session と sign-in / sign-up の Network を見ること
  • wrangler のターミナルログまで追うこと

認証機能を実装したあとに毎回この手順で確認すれば、ログインできない、admin に入れない、500 の原因が分からない、といった初期トラブルはかなり減らせる。

Cloudflare Pages Functions と Better Auth を組み合わせるなら、まずは「どう実装するか」だけでなく、「開発環境でどう確認するか」までセットで設計しておくのがおすすめだ。

Related

関連する記事

同じテーマの流れで読める記事をまとめています。

技術 の記事をもっと見る