腾讯云CloudBase Web身份认证SDK：手机/邮箱/匿名/OAuth登录全攻略

auth-web-cloudbase by tencentcloudbase/skills

573 周安装量

41 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/tencentcloudbase/skills --skill auth-web-cloudbase

云服务 JavaScript 框架安全

🇨🇳中文介绍

激活契约

在以下情况下优先使用

任务是使用 @cloudbase/js-sdk 构建的 CloudBase Web 登录、注册、会话或用户资料流程。

编写代码前请阅读，如果

用户需要登录页面、认证模态框、会话处理或受保护的 Web 路由。请先阅读 auth-tool 以确保提供商已启用。

同时阅读

../auth-tool/SKILL.md 以了解提供商设置
../web-development/SKILL.md 以了解 Web 项目结构和部署

请勿用于

小程序认证、原生 App 认证或服务器端认证设置。

常见错误 / 陷阱

跳过可发布密钥和提供商检查。
用云函数登录逻辑替换内置的 Web 认证。
在 Flutter、React Native 或原生 iOS/Android 代码中复用此流程。

概述

前提条件 : CloudBase 环境 ID (env) : CloudBase 环境区域 ()

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

104,600 周安装

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

102,600 周安装

Azure 配额管理指南：服务限制、容量验证与配额增加方法

79,700 周安装

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

68,100 周安装

使用场景 : 使用 @cloudbase/js-sdk@2.24.0+ 进行用户认证的 Web 前端项目
主要优势 : 兼容 supabase-js API，支持手机、邮箱、匿名、用户名/密码及第三方登录方式 官方@cloudbase/js-sdk CDN: https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js

使用与 web-development 相同的 CDN 地址。在现代打包器项目中推荐使用 npm 安装，对于静态 HTML、无需构建的演示或低门槛示例，使用 CDN 形式。

自动使用 auth-tool-cloudbase 获取 publishable key 并配置登录方式。
如果 auth-tool-cloudbase 失败，让用户前往 https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey 获取 publishable key 并前往 https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage 设置登录方式。

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: `env`, // CloudBase 环境 ID
  region: `region`,  // CloudBase 环境区域，默认为 'ap-shanghai'
  accessKey: 'publishable key', // 必需，从 auth-tool-cloudbase 获取
  auth: { detectSessionInUrl: true }, // 必需
})

const auth = app.auth

1. 手机 OTP (推荐)

自动使用 auth-tool-cloudbase 开启 SMS Login

const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })

自动使用 auth-tool-cloudbase 开启 Email Login

const { data, error } = await auth.signInWithOtp({ email: 'user@example.com' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '654321' })

const { data, error } = await auth.signInWithPassword({ username: 'test_user', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ email: 'user@example.com', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ phone: '13800138000', password: 'pass123' })

4. 注册 (智能：若存在则自动登录)

仅支持邮箱和手机 OTP 注册
自动使用 auth-tool-cloudbase 开启 Email Login 或 SMS Login

// 邮箱 OTP
const { data, error } = await auth.signUp({ email: 'new@example.com', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

// 手机 OTP
const { data, error } = await auth.signUp({ phone: '13800138000', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

自动使用 auth-tool-cloudbase 开启 Anonymous Login

const { data, error } = await auth.signInAnonymously()

6. OAuth (Google/微信)

自动使用 auth-tool-cloudbase 开启 Google Login 或 WeChat Login

const { data, error } = await auth.signInWithOAuth({ provider: 'google' })
window.location.href = data.url // 回调后自动完成

7. 自定义票据

await auth.signInWithCustomTicket(async () => {
  const res = await fetch('/api/ticket')
  return (await res.json()).ticket
})

8. 升级匿名用户

const { data, error } = await auth.getSession()
const { data: signUpData, error: signUpError} = await auth.signUp({
  phone: '13800000000',
  anonymous_token: data.session.access_token,
})
await signUpData.verifyOtp({ token: '123456' })

// 退出登录
const { data, error } = await auth.signOut()

// 获取用户
const { data, error } = await auth.getUser()
console.log(data.user.email, data.user.phone, data.user.user_metadata?.nickName)

// 更新用户 (邮箱、手机除外)
const { data, error } = await auth.updateUser({ nickname: 'New Name', gender: 'MALE', avatar_url: 'url' })

// 更新用户 (邮箱或手机)
const { data, error } = await auth.updateUser({ email: 'new@example.com' })
const { data, error } = await data.verifyOtp({ email: "new@example.com", token: "123456" });

// 修改密码 (已登录)
const { data, error } = await auth.resetPasswordForOld({ old_password: 'old', new_password: 'new' })

// 重置密码 (忘记密码)
const { data, error } = await auth.reauthenticate()
const { data, error } = await data.updateUser({ nonce: '123456', password: 'new' })

// 关联第三方
const { data, error } = await auth.linkIdentity({ provider: 'google' })

// 查看/解绑身份
const { data, error } = await auth.getUserIdentities()
const { data, error } = await auth.unlinkIdentity({ provider: data.identities[0].id })

// 删除账户
const { data, error } = await auth.deleteMe({ password: 'current' })

// 监听状态变化
const { data, error } = auth.onAuthStateChange((event, session, info) => {
  // INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED, PASSWORD_RECOVERY, BIND_IDENTITY
})

// 获取访问令牌
const { data, error } = const { data, error } = await auth.getSession()
fetch('/api/protected', { headers: { Authorization: `Bearer ${data.session?.access_token}` } })

// 刷新用户
const { data, error } = await auth.refreshUser()

declare type User = {
  id: any
  aud: string
  role: string[]
  email: any
  email_confirmed_at: string
  phone: any
  phone_confirmed_at: string
  confirmed_at: string
  last_sign_in_at: string
  app_metadata: {
    provider: any
    providers: any[]
  }
  user_metadata: {
    name: any
    picture: any
    username: any
    gender: any
    locale: any
    uid: any
    nickName: any
    avatarUrl: any
    location: any
    hasPassword: any
  }
  identities: any
  created_at: string
  updated_at: string
  is_anonymous: boolean
}

class PhoneLoginPage {
  async sendCode() {
    const phone = document.getElementById('phone').value
    if (!/^1[3-9]\d{9}$/.test(phone)) return alert('Invalid phone')

    const { data, error } = await auth.signInWithOtp({ phone })
    if (error) return alert('Send failed: ' + error.message)

    this.verifyFunction = data.verify
    document.getElementById('codeSection').style.display = 'block'
    this.startCountdown(60)
  }

  async verifyCode() {
    const code = document.getElementById('code').value
    if (!code) return alert('Enter code')

    const { data, error } = await this.verifyFunction(code)
    if (error) return alert('Verification failed: ' + error.message)

    console.log('Login successful:', data.user)
    window.location.href = '/dashboard'
  }

  startCountdown(seconds) {
    let countdown = seconds
    const btn = document.getElementById('resendBtn')
    btn.disabled = true

    const timer = setInterval(() => {
      countdown--
      btn.innerText = `Resend in ${countdown}s`
      if (countdown <= 0) {
        clearInterval(timer)
        btn.disabled = false
        btn.innerText = 'Resend'
      }
    }, 1000)
  }
}

// 使用 OpenID 静默登录
const { data, error } = await auth.signInWithOpenId() // 微信云模式 (默认)
const { data, error } = await auth.signInWithOpenId({ useWxCloud: false }) // HTTP 模式

// 手机授权登录
const { data, error } = await auth.signInWithPhoneAuth({ phoneCode: 'xxx' })

2026 年 1 月 22 日

🇺🇸English

Activation Contract

Use this first when

The task is a CloudBase Web login, registration, session, or user profile flow built with @cloudbase/js-sdk.

Read before writing code if

The user needs a login page, auth modal, session handling, or protected Web route. Read auth-tool first to ensure providers are enabled.

Then also read

../auth-tool/SKILL.md for provider setup
../web-development/SKILL.md for Web project structure and deployment

Do NOT use for

Mini program auth, native App auth, or server-side auth setup.

Common mistakes / gotchas

Skipping publishable key and provider checks.
Replacing built-in Web auth with cloud function login logic.
Reusing this flow in Flutter, React Native, or native iOS/Android code.

Overview

Prerequisites : CloudBase environment ID (env) Prerequisites : CloudBase environment Region (region)

Core Capabilities

Use Case : Web frontend projects using @cloudbase/js-sdk@2.24.0+ for user authentication
Key Benefits : Compatible with supabase-js API, supports phone, email, anonymous, username/password, and third-party login methods Official@cloudbase/js-sdk CDN: https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js

Use the same CDN address as web-development. Prefer npm installation in modern bundler projects, and use the CDN form for static HTML, no-build demos, or low-friction examples.

Prerequisites

Automatically use auth-tool-cloudbase to get publishable key and configure login methods.
If auth-tool-cloudbase failed, let user go to https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey to get publishable key and https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage to set up login methods

Quick Start

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: `env`, // CloudBase environment ID
  region: `region`,  // CloudBase environment Region, default 'ap-shanghai'
  accessKey: 'publishable key', // required, get from auth-tool-cloudbase
  auth: { detectSessionInUrl: true }, // required
})

const auth = app.auth
``

---

## Login Methods

**1. Phone OTP (Recommended)**
- Automatically use `auth-tool-cloudbase` turn on `SMS Login`
```js
const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })

2. Email OTP

Automatically use auth-tool-cloudbase turn on Email Login

const { data, error } = await auth.signInWithOtp({ email: 'user@example.com' }) const { data: loginData, error: loginError } = await data.verifyOtp({ token: '654321' })

3. Password

const { data, error } = await auth.signInWithPassword({ username: 'test_user', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ email: 'user@example.com', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ phone: '13800138000', password: 'pass123' })

4. Registration (Smart: auto-login if exists)

Only support email and phone otp registration
Automatically use auth-tool-cloudbase turn on Email Login or SMS Login

// Email Otp const { data, error } = await auth.signUp({ email: 'new@example.com', nickname: 'User' }) const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

// Phone Otp const { data, error } = await auth.signUp({ phone: '13800138000', nickname: 'User' }) const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

5. Anonymous

Automatically use auth-tool-cloudbase turn on Anonymous Login

const { data, error } = await auth.signInAnonymously()

6. OAuth (Google/WeChat)

Automatically use auth-tool-cloudbase turn on Google Login or WeChat Login

const { data, error } = await auth.signInWithOAuth({ provider: 'google' }) window.location.href = data.url // Auto-complete after callback

7. Custom Ticket

await auth.signInWithCustomTicket(async () => {
  const res = await fetch('/api/ticket')
  return (await res.json()).ticket
})

8. Upgrade Anonymous

const { data, error } = await auth.getSession()
const { data: signUpData, error: signUpError} = await auth.signUp({
  phone: '13800000000',
  anonymous_token: data.session.access_token,
})
await signUpData.verifyOtp({ token: '123456' })

User Management

// Sign out
const { data, error } = await auth.signOut()

// Get user
const { data, error } = await auth.getUser()
console.log(data.user.email, data.user.phone, data.user.user_metadata?.nickName)

// Update user (except email, phone)
const { data, error } = await auth.updateUser({ nickname: 'New Name', gender: 'MALE', avatar_url: 'url' })

// Update user (email or phone)
const { data, error } = await auth.updateUser({ email: 'new@example.com' })
const { data, error } = await data.verifyOtp({ email: "new@example.com", token: "123456" });

// Change password (logged in)
const { data, error } = await auth.resetPasswordForOld({ old_password: 'old', new_password: 'new' })

// Reset password (forgot)
const { data, error } = await auth.reauthenticate()
const { data, error } = await data.updateUser({ nonce: '123456', password: 'new' })

// Link third-party
const { data, error } = await auth.linkIdentity({ provider: 'google' })

// View/Unlink identities
const { data, error } = await auth.getUserIdentities()
const { data, error } = await auth.unlinkIdentity({ provider: data.identities[0].id })

// Delete account
const { data, error } = await auth.deleteMe({ password: 'current' })

// Listen to state changes
const { data, error } = auth.onAuthStateChange((event, session, info) => {
  // INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED, PASSWORD_RECOVERY, BIND_IDENTITY
})

// Get access token
const { data, error } = const { data, error } = await auth.getSession()
fetch('/api/protected', { headers: { Authorization: `Bearer ${data.session?.access_token}` } })

// Refresh user
const { data, error } = await auth.refreshUser()

User Type

declare type User = {
  id: any
  aud: string
  role: string[]
  email: any
  email_confirmed_at: string
  phone: any
  phone_confirmed_at: string
  confirmed_at: string
  last_sign_in_at: string
  app_metadata: {
    provider: any
    providers: any[]
  }
  user_metadata: {
    name: any
    picture: any
    username: any
    gender: any
    locale: any
    uid: any
    nickName: any
    avatarUrl: any
    location: any
    hasPassword: any
  }
  identities: any
  created_at: string
  updated_at: string
  is_anonymous: boolean
}

Complete Example

class PhoneLoginPage {
  async sendCode() {
    const phone = document.getElementById('phone').value
    if (!/^1[3-9]\d{9}$/.test(phone)) return alert('Invalid phone')

    const { data, error } = await auth.signInWithOtp({ phone })
    if (error) return alert('Send failed: ' + error.message)

    this.verifyFunction = data.verify
    document.getElementById('codeSection').style.display = 'block'
    this.startCountdown(60)
  }

  async verifyCode() {
    const code = document.getElementById('code').value
    if (!code) return alert('Enter code')

    const { data, error } = await this.verifyFunction(code)
    if (error) return alert('Verification failed: ' + error.message)

    console.log('Login successful:', data.user)
    window.location.href = '/dashboard'
  }

  startCountdown(seconds) {
    let countdown = seconds
    const btn = document.getElementById('resendBtn')
    btn.disabled = true

    const timer = setInterval(() => {
      countdown--
      btn.innerText = `Resend in ${countdown}s`
      if (countdown <= 0) {
        clearInterval(timer)
        btn.disabled = false
        btn.innerText = 'Resend'
      }
    }, 1000)
  }
}

WeChat Mini Program

// Silent login with OpenID
const { data, error } = await auth.signInWithOpenId() // WeChat Cloud mode (default)
const { data, error } = await auth.signInWithOpenId({ useWxCloud: false }) // HTTP mode

// Phone authorization login
const { data, error } = await auth.signInWithPhoneAuth({ phoneCode: 'xxx' })

Weekly Installs

544

Repository

tencentcloudbase/skills

GitHub Stars

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

opencode477

codex475

gemini-cli469

github-copilot455

kimi-cli448

cursor446

Supabase Postgres 最佳实践指南 - 8大类别性能优化规则与SQL示例

57,300 周安装