Puter JS SDK `puter.auth.signOut()` 详解：登出当前用户的本地会话清理机制-创锋一号

Puter JS SDK`puter.auth.signOut()`详解：登出当前用户的本地会话清理机制

【免费下载链接】puter🌐 The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter

puter.auth.signOut()是 Puter JavaScript SDK 中负责将当前用户从应用登出的方法。它属于 puter.auth 认证模块（文档见 signOut.md），适用于**网站（websites）与 Puter 应用（apps）**两类平台，用于让你的应用具备"退出登录/切换账号"能力。读完本文，你将掌握该 API 的调用语法、底层令牌清理机制、本地存储行为、不同运行环境的限制，以及如何与signIn()、isSignedIn()、getUser()配合搭建一套完整的登录/登出流程。

方法概述：`puter.auth.signOut()`

该方法将当前用户从你的应用中登出。与signIn()需要弹窗、返回 Promise 不同，signOut()是一个纯本地、同步、无返回值的操作——它只负责丢弃 SDK 在当前页面持有的认证令牌，并不会向服务端发起任何"注销会话"的网络请求。

一个典型使用场景是：在页面上放置"退出"或"切换账号"按钮，点击后调用本方法清除本站点保存的令牌，用户下次再调用需要鉴权的puter.*能力时，SDK 会重新引导其完成登录。

语法

puter.auth.signOut()

参数

无。

该方法不接受任何参数，也不需要回调函数。

返回值

无（返回undefined）。

调用成功后，puter.auth.isSignedIn()将立即返回false。

底层实现：一次本地令牌清理的完整链条

从源码层面看，Auth.js 中的signOut实现非常简洁——它只是转发调用 SDK 核心实例的resetAuthToken()：

// src/puter-js/src/modules/Auth.js signOut = () => { puter.resetAuthToken(); };

而 index.js 中的resetAuthToken()与_clearAuthToken()才是真正执行清理的地方：

// src/puter-js/src/index.js _clearAuthToken = function () { this.authToken = null; if (this.env === 'web' || this.env === 'app') { try { localStorage.removeItem(STORAGE_KEY_V2); // 'puter.auth.token.v2' localStorage.removeItem(STORAGE_KEY_ORIGIN_V2); // 'puter.auth.token.origin.v2' localStorage.removeItem(STORAGE_KEY_V1); // 'puter.auth.token'（已废弃的 v1 键） } catch (error) { console.error('Error accessing localStorage:', error); } } }; resetAuthToken = function () { if (this.env === 'web-worker' || this.env === 'service-worker') { throw new Error('Sign out is not permitted from WebWorkers or ServiceWorkers'); } this._clearAuthToken(); this._emitAuthStateChanged(); };

由此可以归纳出signOut()的三个关键动作：

清空内存令牌：将 SDK 实例的authToken置为null，后续所有 API 请求不再携带Authorization: Bearer <token>头；
清除本地持久化令牌：当 SDK 运行在第三方网站（web）或 Puter 应用（app）环境时，同时移除localStorage中的三个键——puter.auth.token.v2（当前 v2 令牌）、puter.auth.token.origin.v2（令牌绑定的 API 来源）、puter.auth.token（已停用的 v1 遗留键，保证其不会比新令牌存活更久）；
广播认证状态变化：调用_emitAuthStateChanged()，让 SDK 内部监听认证状态变化的逻辑（例如需根据登录态切换的连接、缓存等）同步更新。

值得注意的是，令牌写入方 setAuthToken 会在web/app环境下把令牌连同其来源绑定写入localStorage（令牌只能重放给铸造它的那个 API Origin），而signOut()的清理逻辑与此严格对称，确保不会残留任何可被下次启动拾取的凭证。

关键行为与事实

围绕源码与测试用例（auth.suite.ts），signOut()有以下行为要点值得注意：

登出是"应用本地"的，而非"全局"的：它只清除当前浏览器 Origin/SDK 实例持有的令牌。用户的 Puter 账号会话本身不会被销毁，你在其他站点或设备上的登录状态不受影响。这也意味着，如果只是想让当前页面恢复为"未登录"以便重新走登录流程，调用本方法即可，无需任何服务端配合。
登出后isSignedIn()立即变为false：测试用例"signOut clears the session client-side"验证了signOut()之后puter.auth.isSignedIn()返回false，随后用setAuthToken()恢复令牌后isSignedIn()又回到true。
登出后调用getUser()会快速失败：当 SDK 内没有任何令牌时，getUser()会直接抛出{ status: 401, message: 'Unauthorized' }，而不是真的发起一次注定失败的请求。
Worker 环境禁止登出：resetAuthToken()在web-worker与service-worker环境下会抛出Error('Sign out is not permitted from WebWorkers or ServiceWorkers')。测试用例"signOut is refused in every worker environment"强制将环境切换为web-worker、service-worker后断言signOut()被拒绝，且被拒绝的登出必须保持令牌完好（isSignedIn()仍为true）。这与 Puter 的 Serverless Workers 运行时模型一致：Worker 的令牌由调用它的会话/事件提供，Worker 自身不应有登出语义。

完整示例：带登录/登出切换的页面

以下是基于官方文档示例（signOut.md）扩展出的可运行页面，演示按钮驱动的登出，以及登录后回跳再登出的完整闭环：

<!-- 仅登出用途的页面：加载 SDK 后立即清除本站点登录态 --> <html> <body> <script src="https://js.puter.com/v2/"></script> <script> puter.auth.signOut(); // 此时 puter.auth.isSignedIn() 已返回 false console.log('Signed out:', !puter.auth.isSignedIn()); </script> </body> </html>

<!-- 含"退出登录"按钮的应用页面 --> <html> <body> <script src="https://js.puter.com/v2/"></script> <button id="sign-out" hidden>Sign out</button> <script> // 页面加载时依据登录态决定是否显示登出按钮 if (puter.auth.isSignedIn()) { document.getElementById('sign-out').hidden = false; } // signOut() 必须由用户操作触发，与 signIn() 打开弹窗的约束不同， // 它本身不弹窗，但放在按钮事件里能保证页面交互语义清晰。 document.getElementById('sign-out').addEventListener('click', () => { puter.auth.signOut(); location.reload(); // 刷新页面以应用"未登录"界面 }); </script> </body> </html>

作为参照，仓库的 puter-js/test/index.html 中即展示了类似的实战用法：页面通过isSignedIn()判断登录态，在用户已登录时渲染(logout)链接，点击后调用await puter.auth.signOut();完成登出。

与`signIn()`、`isSignedIn()`、`getUser()`配合使用

signOut()在puter.auth模块中通常与下列方法搭配，构成完整的认证闭环：

API	作用	说明
puter.auth.signIn()	发起登录	打开认证弹窗，返回解析为`SignInResult`的 Promise；必须由用户手势（如 click）触发
puter.auth.signOut()	退出登录	本地清除令牌，无参数、无返回值
puter.auth.isSignedIn()	查询登录态	返回`true`/`false`，适合在渲染 UI 前判断
puter.auth.getUser()	读取用户信息	未登录时快速抛出`401 Unauthorized`

文档 signIn.md 中特别强调：Puter SDK 中绝大多数方法都会自动完成认证，signIn()/signOut()等仅在你希望自己掌控认证流程时才需要显式调用。因此一个常见的判断标准是：如果"登出"仅是某个一次性操作的附带步骤，且页面即将跳转/刷新，直接调用puter.auth.signOut()即可；如果需要依据登出结果即时切换 UI，再结合isSignedIn()与getUser()的组合状态刷新视图。

需要留意的是，对于在 Puter 平台上运行的 App（env === 'app'），其登录态来自启动它的 Puter 会话（令牌由启动 URL 注入），因此该类环境更多使用isSignedIn()/getUser()读取会话身份；而"登出"按钮这类功能通常属于第三方网站集成场景（env === 'web'），调用方应结合自身页面路由决定登出后的去向。

运行时环境与适用限制

支持平台：websites、apps（由文档 frontmatter 中的platforms字段标注）。
不支持 Worker：在web-worker/service-worker（含 Puter Serverless Workers）环境中调用将抛出异常，且不会破坏现有令牌。
Node.js：signOut()面向浏览器 DOM 场景设计；SDK 在 Node.js/服务端环境中通常由宿主直接管理令牌生命周期，不依赖本方法做本地清理。
无服务端副作用：如需在服务端同时吊销令牌或结束会话，请结合你的后端认证策略另行处理，signOut()不承担服务端职责。

企业官网建设流程全解析