认证提供者负责 用户身份验证 和 Studio 的访问控制。它们决定谁可以登录和编辑内容。
| 功能 | GitHub OAuth | GitLab OAuth | Google OAuth | 自定义认证 |
|---|---|---|---|---|
| 身份验证 | ✅ | ✅ | ✅ | ✅ |
| Git 操作 | ✅ 自动（OAuth 令牌） | ✅ 自动（OAuth 令牌） | ⚠️ 需要个人访问令牌（PAT） | ⚠️ 需要个人访问令牌（PAT） |
| 访问控制 | ✅ OAuth 作用域 | ✅ OAuth 作用域 | ⚠️ 管理员白名单 | ⚠️ 自定义逻辑 |
| 安全认证流程 | ✅ 提供者管理 | ✅ 提供者管理 | ✅ 提供者管理 | ⚠️ 自行管理 |
GitHub OAuth 提供身份验证并自动实现 Git 访问。通过 GitHub 认证的用户可以立即推送更改到仓库。
访问 GitHub 开发者设置，点击 New OAuth App
填写必填字段：
https://yourdomain.comhttps://yourdomain.com/__nuxt_studio/auth/githubhttp://localhost:3000/__nuxt_studio/auth/github创建 OAuth 应用后，您将获得：
将 GitHub OAuth 凭据添加到您的部署平台环境变量或 .env 文件：
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
# 可选：限制特定用户访问
# STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com
GitLab OAuth 提供身份验证并自动实现 Git 访问。通过 GitLab 认证的用户可以立即推送更改到仓库。
访问 GitLab 的 用户设置 → 应用（或您的群组/组织设置），创建一个 新建应用程序。
填写必填字段：
https://yourdomain.com/__nuxt_studio/auth/gitlabapi（发布必需）http://localhost:3000/__nuxt_studio/auth/gitlab创建 OAuth 应用后，您将获得：
将 GitLab OAuth 凭据添加到您的部署平台环境变量或 .env 文件：
STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>
# 可选：限制特定用户访问
# STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com
Google OAuth 适合没有 GitHub 或 GitLab 账号的非技术用户。
访问 Google Cloud 控制台，选择或创建一个项目，导航至 API 与服务 → 凭据。
点击 创建凭据，选择 OAuth 客户端 ID，应用类型选择 Web 应用。
填写必填字段：
https://yourdomain.com/__nuxt_studio/auth/googlehttp://localhost:3000/__nuxt_studio/auth/google创建 OAuth 客户端后，您将获得：
由于 Google 不支持 Git 访问，您还必须配置一个 个人访问令牌 用于仓库操作。
添加 Google OAuth 凭据、个人访问令牌及管理员列表：
STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com
STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com
STUDIO_GOOGLE_MODERATORS 环境变量对 Google OAuth 必填。只有列表中的邮箱用户能访问 Studio。若需完全掌控身份认证，可使用 Studio 会话工具实现自己的认证逻辑（密码表单、SSO、LDAP 等）。
您必须基于所用 Git 提供者配置个人访问令牌以支持仓库操作。
# 针对 GitHub 仓库
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>
# 针对 GitLab 仓库
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
详细创建说明见 Git 提供者。
setStudioUserSession(event, user)，传入 StudioUserSession 对象以创建会话clearStudioUserSession(event) 处理登出，清除会话调用 setStudioUserSession 时，必须提供：
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
name | string | ✅ | 用户显示名称 |
email | string | ✅ | 用户邮箱 |
providerId | string | ❌ | 用户的唯一标识符 |
avatar | string | ❌ | 用户头像图片的 URL |
import { eventHandler, readBody, createError } from 'h3'
import { setStudioUserSession } from '#imports'
export default eventHandler(async (event) => {
const { email, password } = await readBody<{ email?: string, password?: string }>(event)
// ⚠️ 在此实现您自己的安全验证逻辑
// 本示例简单示范，请使用安全的密码哈希和验证
const user = await validateCredentials(email, password)
if (!user) {
throw createError({
statusCode: 401,
message: '无效的凭据'
})
}
await setStudioUserSession(event, {
providerId: user.id,
name: user.name,
email: user.email,
avatar: user.avatar || ''
})
return { ok: true }
})
import { eventHandler } from 'h3'
import { clearStudioUserSession } from '#imports'
export default eventHandler(async (event) => {
await clearStudioUserSession(event)
return { ok: true }
})
成功设置会话后，将用户重定向至应用根路径（/）。Studio 会自动检测会话并为该用户激活。
// 调用 setStudioUserSession 后...
return sendRedirect(event, '/')
您可以通过 STUDIO_{PROVIDER}_MODERATORS 环境变量定义授权用户白名单，限制 Studio 访问。
# GitHub OAuth 管理员
STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com
# GitLab OAuth 管理员
STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com
# Google OAuth 管理员（必填）
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com
管理员列表为逗号分隔的邮箱地址。只有列表中的邮箱用户被允许访问。
| 提供者 | 管理员列表 | 行为说明 |
|---|---|---|
| GitHub OAuth | 可选 | 为空时，所有通过 OAuth 认证用户均可访问 |
| GitLab OAuth | 可选 | 为空时，所有通过 OAuth 认证用户均可访问 |
| Google OAuth | 必填 | 无管理员列表时，无人可访问 Studio |
| 自定义认证 | 不适用 | 自行实现访问控制逻辑 |
默认情况下，Studio 使用您的部署 URL 作为 OAuth 回调地址。如需自定义：
# GitHub OAuth
STUDIO_GITHUB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/github
# GitLab OAuth
STUDIO_GITLAB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/gitlab
# Google OAuth
STUDIO_GOOGLE_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/google
/_studio（或您配置的路由）即可开始编辑和发布内容。