部署

環境變數

Auth.js 函式庫需要您設定 AUTH_SECRET 環境變數。這用於加密 Cookie 和令牌。它應該是至少 32 個字元的加密安全隨機字串

npm exec auth secret

pnpm exec auth secret

yarn auth secret

bunx auth secret

如果您使用 OAuth 供應商，您的供應商會提供您客戶端 ID 和客戶端密碼，您也需要將它們設定為環境變數（如果是像 Auth0 這樣的 OIDC 供應商，可能還需要第三個 issuer 值，請參閱供應商的特定文件）。

AUTH_OKTA_ID=abc
AUTH_OKTA_SECRET=abc
AUTH_OKTA_ISSUER=abc

AUTH_SECRET

這是唯一嚴格要求的環境變數。它是用於編碼 JWT 和加密傳輸中內容的密碼。如上所述，我們建議至少使用 32 個字元的隨機字串。這可以使用 CLI 透過 npm exec auth secret 或使用 openssl 透過 openssl rand -base64 33 產生。

AUTH_TRUST_HOST

當在反向代理後面部署您的應用程式時，您需要將 AUTH_TRUST_HOST 設定為 true。這會告知 Auth.js 信任來自反向代理的 X-Forwarded-Host 標頭。如果我們偵測到環境變數指示您的應用程式正在受支援的託管供應商之一上執行，Auth.js 會自動推斷這是 true。目前支援 VERCEL 和 CF_PAGES (Cloudflare Pages)。

AUTH_URL

對於 v5，由於主機是從請求標頭推斷出來的，因此此環境變數大多是不必要的。但是，如果您使用不同的基本路徑，您也可以設定此環境變數。例如，AUTH_URL=https://127.0.0.1:3000/web/auth 或 AUTH_URL=https://company.com/app1/auth

AUTH_REDIRECT_PROXY_URL

此環境變數僅設計用於進階使用案例，例如當使用 Auth.js 作為預覽部署的代理時。如需更多詳細資訊，請參閱下面的保護預覽部署區段。

無伺服器

1. 為您想要的環境建立所需的環境變數。別忘了也要為您選擇的供應商加入所需的環境變數（即 OAuth clientId / clientSecret 等）。
2. 當使用 OAuth 供應商時，請確保正確設定您生產 URL 的回呼 URL。許多 OAuth 供應商只允許您為每個 OAuth 應用程式設定 1 個 callbackUrl。在這種情況下，您需要為每個環境（開發、生產等）建立個別的應用程式。其他供應商（如 Google）允許您將許多 callbackUrl 新增至一個應用程式。
   • 預設情況下，next-auth (Next.js) 應用程式的回呼 URL 應如下所示：https://company.com/api/auth/callback/[provider]（將 company.com 替換為您的網域，並將 provider 替換為供應商名稱，例如 github）。
   • 預設情況下，所有其他框架 (@auth/sveltekit、@auth/express 等) 都會使用路徑 /auth/callback/[provider]。
3. 部署！在設定好這兩個先決條件後，您應該能夠在 Netlify、Vercel 等平台上部署並執行您的 Auth.js 應用程式。

可觀測性

為了將您目前使用者的詳細資訊傳遞到您的可觀測性工具，您可以使用 Auth.js 提供的回呼。例如，在 session 回呼中，您可以將 user.id 傳遞到 Sentry。

import * as Sentry from "@sentry/browser"
import NextAuth from "next-auth"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  callbacks: {
    session({ session, user }) {
      const scope = Sentry.getCurrentScope()
 
      scope.setUser({
        id: user.id,
        email: user.email,
      })
 
      return session
    },
  },
})

自架式

Auth.js 也可以部署在您可以部署所選框架的任何地方。請查看框架關於自架託管的文件。

Docker

在 Docker 環境中，請務必在您的 Auth.js 設定中設定 trustHost: true 或將 AUTH_TRUST_HOST 環境變數設定為 true。

我們的範例應用程式也透過 Docker 託管，這裡有範例 (請參閱原始碼)。下方是一個使用 Auth.js 的 Next.js 應用程式的 Dockerfile 範例。

# syntax=docker/dockerfile:1
# syntax=docker/dockerfile:1
FROM node:20-alpine AS base
 
# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
# Install dependencies
COPY package.json pnpm-lock.yaml* ./
RUN corepack enable pnpm && pnpm i --frozen-lockfile
 
# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.dev.org.tw/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED 1
 
RUN corepack enable pnpm && pnpm build
 
# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app
 
ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED 1
 
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
COPY --from=builder /app/public ./public
 
# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Automatically leverage output traces to reduce image size
# https://nextjs.dev.org.tw/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT 3000
ENV HOSTNAME "0.0.0.0"
 
# server.js is created by next build from the standalone output
# https://nextjs.dev.org.tw/docs/pages/api-reference/next-config-js/output
CMD ["node", "server.js"]

保護預覽部署

大多數 OAuth 供應商無法配置多個回呼 URL 或使用萬用字元。

然而，Auth.js 支援預覽部署，即使是使用 OAuth 供應商也一樣。概念是擁有一個部署，將驗證請求代理到您主要應用程式的動態 URL。因此，您可以擁有一個穩定的部署，例如在 auth.company.com，您可以在這裡指向所有 OAuth 供應商的 callbackUrl，然後這個應用程式會在成功驗證後，將使用者重新導向回預覽部署 URL，例如 https://git-abc123-myapp.vercel.app。請按照以下步驟開始使用 Auth.js 保護預覽部署。

1. 確定一個穩定的部署 URL。例如，一個 URL 在不同建置之間不會變更的部署。例如 auth.yourdomain.com (使用子網域並非必要條件，這也可以是主網站的 URL，例如)。
2. 在預覽和穩定環境中，將 AUTH_REDIRECT_PROXY_URL 設定為該穩定的部署 URL，包括 Auth.js 處理路由的路徑。例如：(https://auth.yourdomain.com/api/auth)
3. 更新您 OAuth 供應商配置中的 callbackUrl，以使用穩定的部署 URL。例如，對於 GitHub，它會是 https://auth.yourdomain.com/api/auth/callback/github。

有趣的事實：我們所有的範例應用程式都使用代理功能！