Puter.js 登录状态检测指南读懂 puter.auth.isSignedIn() 的前世今生与实战用法【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.auth.isSignedIn()是 Puter.js 认证模块中用于同步判断当前用户是否已登录的最轻量接口。无论你的应用运行在第三方网站上、Puter 平台内App、Node.js 还是 Worker 运行时它都能在不发起任何网络请求、不弹出任何登录框的前提下立即返回一个布尔值是编写登录门控逻辑最常用的一把钥匙。读完本文你将掌握该 API 的语法细节、它与signIn()/signOut()/getUser()的分工关系以及隐藏在源码与测试背后的完整 token 生命周期。速览语法、参数与返回值该 API 定义于官方文档 Auth/isSignedIn.md其元信息声明支持的平台为websites、apps、nodejs、workers四类运行时。语法puter.auth.isSignedIn()参数无。返回值用户当前已登录返回布尔值true用户未登录返回布尔值false。它不会像puter.auth.getUser()那样发起/whoami请求也不会像puter.auth.signIn()那样打开授权弹窗因此可以放心地在页面渲染、按钮状态切换等同步上下文中调用。可直接运行的示例官方文档原样示例html body script srchttps://js.puter.com/v2//script script puter.print(Sign in status: ${puter.auth.isSignedIn()}); /script /body /html说明https://js.puter.com/v2/是 Puter.js 官方托管的 SDK 入口。如果部署的是自托管环境也可以基于仓库内 src/puter-js 自行构建并托管该 SDK页面加载逻辑一致。底层实现为什么它是纯同步判断要理解isSignedIn()的语义最直接的方式是阅读其源码实现。该方法是 Auth 模块 中一个极简的箭头函数/** * Whether the user is currently signed in. * * type {() boolean} */ isSignedIn () { if ( puter.authToken ) { return true; } else { return false; } };见 Auth.js从源码可以看出两个关键事实它判断的是客户端是否持有一个非空的 authToken而非服务端是否认可这个 token。这个authToken是 SDK 在内存中维护的登录凭证index.js 中初始化为authToken null。它是同步方法内部只是做一次真值判断没有任何 Promise、XHR 或弹窗逻辑因此永远不会因为网络延迟而阻塞也永远不会被浏览器拦截。与它形成对比的是同模块内的getUser()/whoami()这两个方法会真正调用后端/whoami接口去拉取用户资料并且在没有 token 时立刻抛错伪造服务端响应{ status: 401, message: Unauthorized }见 Auth.js。而 SDK 的注释也明确指出需要确定答案且接受随之而来的登录提示的调用方应使用puter.auth.getUser()——换句话说isSignedIn()适合只想安静地问一句、不想打扰用户的场景。authToken 从哪来一次完整的登录状态生命周期既然isSignedIn()只是检查puter.authToken那么理解这个 token 什么时候被写入、什么时候被清除就等于理解了该 API 的全部行为边界。1. 通过 signIn() 弹窗写入在第三方网站上SDK 内部称之为env web登录通常由 signIn 文档 描述的puter.auth.signIn()驱动它打开 Puter GUI 的授权弹窗用户完成登录后弹窗通过postMessage回传puter.token消息SDK 校验消息来源必须是defaultGUIOrigin、来源窗口必须是它自己打开的弹窗、msg_id必须匹配后调用puter.setAuthToken(e.data.token)写入 token随后resolve。此时再调用isSignedIn()就会返回true。2. 页面刷新后从 localStorage 恢复SDK 启动引导逻辑index.js会根据运行环境恢复会话在web 环境下token 持久化于 localStorage键名为puter.auth.token.v2旧版本遗留键puter.auth.token只删不读见 index.js恢复 token 前会校验其绑定的 API originSTORAGE_KEY_ORIGIN_V2只把 token 重放到它签发时对应的 origin防止 URL 可控的puter.api_origin窃取其他站点存储的凭证在app 环境下SDK 被 Puter GUI 以启动参数?puter.auth.token...方式拉起token 由启动它的 Puter 会话直接提供在gui 环境下SDK 运行在 Puter 桌面本身token 直接取自window.auth_token。因此上次登录过、今天刷新页面后isSignedIn()依然返回true这个用户体验正是由这套引导恢复逻辑保证的。3. 通过 signOut() 清除signOut 文档 描述的puter.auth.signOut()内部调用puter.resetAuthToken()见 Auth.js该方法会清空内存 token 并同步删除 localStorage 中的持久化 token随后isSignedIn()立即返回false。需要留意resetAuthToken在web-worker/service-worker环境下会直接抛错拒绝登出见 index.js所以 Worker 运行时中的会话是无法自行登出的。4. token 被后端判定失效时被清除isSignedIn()只检查本地 token 是否存在并不保证该 token 在服务端仍然有效。若 token 已过期或被吊销下一次 API 调用会收到 401此时 SDK 的网络层会触发reauth 协调流程先丢弃这个中毒的 tokenauthToken置回null再按环境决定是弹出登录框还是抛出结构化的reauth_required错误。也就是说一个失效会话在 reauth 触发并完成前isSignedIn()可能短暂地仍返回true而在 reauth 丢弃 token 之后它会恢复为false。该行为由测试用例a token the backend rejects routes through reauth与reauth is a no-op inside the Puter GUI显式验证见 auth.suite.ts。实战用 isSignedIn() 搭建登录门控界面把上述 API 组合起来就能写出一个结构完整、可直接复制到任意 HTML 页面中的登录/登出门控示例。下面这个示例继承并扩充了官方文档中的 auth-is-signed-in 示例初次加载时根据登录状态渲染不同按钮点击登录按钮完成signIn()后刷新状态点击登出按钮后回到未登录视图。html body script srchttps://js.puter.com/v2//script div idapp p idstatusLoading…/p button idsign-in styledisplay:noneSign in with Puter/button button idsign-out styledisplay:noneSign out/button /div script function render() { const signedIn puter.auth.isSignedIn(); document.getElementById(status).textContent signedIn ? Signed in : Not signed in; document.getElementById(sign-in).style.display signedIn ? none : inline-block; document.getElementById(sign-out).style.display signedIn ? inline-block : none; } // signIn() 必须由用户手势如点击触发否则浏览器会拦截弹窗。 document.getElementById(sign-in).addEventListener(click, async () { try { const res await puter.auth.signIn(); console.log(Signed in as, res.username); } catch (err) { // 可能的错误popup_blocked / auth_window_closed / not_available_in_app console.error(err.error, err.msg); } render(); }); document.getElementById(sign-out).addEventListener(click, () { puter.auth.signOut(); render(); }); render(); /script /body /html当希望进一步展示用户信息时可在isSignedIn()返回true后调用puter.auth.getUser()或等价的puter.auth.whoami()获取uuid、username等资料用户对象字段的完整定义可查看 Auth.js 顶部的 JSDoc。边界与陷阱小结围绕isSignedIn()有几点值得在生产代码中注意场景表现依据从第三方网站发起登录必须由点击等用户手势调用signIn()否则弹窗被拦截rejectpopup_blockedsignIn.md在 Puter 平台 App 内调用signIn()直接 rejectnot_available_in_appApp 的 token 由启动它的会话提供此时应直接使用getUser()Auth.js在 Worker 内调用signOut()抛错拒绝会话无法自行登出index.jstoken 过期/被吊销isSignedIn()的本地判断与服务端实际校验存在时间差依赖服务端判定时请使用会真实请求/whoami的getUser()auth.suite.ts需要静默体验临时用户signIn({ attempt_temp_user_creation: true })可为用户自动创建临时账号无需注册即可完成登录signIn.md测试验证这些行为是如何被保证的仓库为认证模块提供了多层测试可作为行为契约参考单元/集成测试 auth.suite.ts 中用例isSignedIn reports true with a valid token断言持有合法 token 时返回truesignOut clears the session client-side断言登出后返回false并可在重新写入 token 后恢复signOut is refused in every worker environment则验证在web-worker、service-worker下被拒绝的登出不会破坏原有登录状态见 auth.suite.ts。跨域交互测试 signin.test.js 中testSignInPostMessage在完成一次真实的弹窗登录后断言SDK 采纳了返回的 token且puter.auth.isSignedIn()在成功登录后为真见 signin.test.js。该测试需在非 Puter GUI 源下手动逐条运行。相关 API 导航puter.auth.isSignedIn()只是认证模块的一个成员。完整的认证能力由以下几部分组成Auth.md——认证模块总览涵盖全部功能与聚合示例signIn.md——发起登录仅限网站平台需用户手势触发signOut.md——登出当前用户getUser.md——获取当前登录用户信息getMonthlyUsage.md 与 getDetailedAppUsage.md——查询月度资源用量与单应用用量明细。在动手之前请记住最核心的一条心法大多数 Puter.js 方法都会自动完成鉴权isSignedIn()是少数需要你主动调用的体检式接口——它只负责告诉你本地的钥匙在不在而真正开门验证身份的是那些带网络请求的方法。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考