跳到主要内容

Token 刷新与错误处理

credentials_error 错误说明​

当使用 @cloudbase/js-sdk 时，登录态可能会因以下原因失效，触发 credentials_error 事件：

  1. refresh_token 过期: refresh_token 超过有效期，无法刷新 access_token，需要用户重新登录
  2. Token 被更新: 账号在其他设备登录，导致当前设备的 token 失效

配置 Token 有效期​

可以在 云开发平台 - 身份认证 - Token 管理 中配置 Token 有效期：

  • access_token 有效期: 建议设置为 7200 秒 (2小时)
  • refresh_token 有效期: 建议设置为 2592000 秒 (30天)
提示

配置修改后，仅对新登录的用户生效。已登录用户的 token 有效期不会改变。

处理 credentials_error 事件​

基础处理​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 监听登录态变化，处理 credentials_error
auth.onLoginStateChanged((params) => {
  const { eventType, msg } = params?.data || {};
  
  switch (eventType) {
    case "credentials_error":
      // 方式一: refresh_token 过期，需要重新登录
      if (msg && msg.includes("refresh_token")) {
        console.warn("登录已过期，请重新登录");
        // 跳转到登录页或调用登录弹窗
        auth.toDefaultLoginPage();
      }
      
      // 方式二: 其他设备登录，token 被更新
      if (msg && msg.includes("token updated")) {
        console.warn("账号在其他设备登录，请重新验证");
        // 提示用户重新登录
        auth.toDefaultLoginPage();
      }
      break;
      
    case "sign_out":
      // 处理登出逻辑
      console.log("用户已登出");
      break;
      
    case "sign_in":
      // 处理登录成功逻辑
      console.log("用户已登录");
      break;
  }
});

小程序中的处理​

在微信小程序中，可以结合 UI 提示优化用户体验：

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai",
});

const auth = app.auth();

auth.onLoginStateChanged((params) => {
  const { eventType, msg } = params?.data || {};
  
  if (eventType === "credentials_error") {
    wx.showModal({
      title: "登录过期",
      content: "您的登录已过期，请重新登录",
      confirmText: "重新登录",
      success: (res) => {
        if (res.confirm) {
          // 跳转到登录页面
          wx.navigateTo({
            url: "/pages/login/login",
          });
        }
      },
    });
  }
});

使用 Publishable Key 避免登录前的错误​

如果需要在用户登录前查询数据模型（如展示首页文章列表），可以使用 Publishable Key + 匿名身份查询，避免 credentials_error：

import cloudbases from "@cloudbase/js-sdk/app";
import { registerAuth } from "@cloudbase/js-sdk/auth";
import { registerModel } from "@cloudbase/js-sdk/model";

registerAuth(cloudbases);
registerModel(cloudbases);

const app = cloudbases.init({
  env: "your-env-id",
  accessKey: "<YOUR_PUBLISHABLE_KEY>", // 从控制台获取
});

// 登录前可以匿名查询
const models = app.models;
const articles = await models.article.list();

// 需要鉴权时再登录
await app.auth().signInAnonymously();

获取 Publishable Key:

  1. 访问 云开发平台 - API Key 管理
  2. 创建或复制 Publishable Key
  3. 在初始化时传入 accessKey 参数

最佳实践​

  1. 全局监听: 在应用启动时（如 App.onLaunch）注册 onLoginStateChanged 监听器
  2. 用户提示: 使用 Modal 或 Toast 提示用户登录已过期
  3. 自动重定向: 登录过期后自动跳转到登录页
  4. 保存状态: 记录用户当前页面路径，登录后跳转回原页面