ThreeUI CLI 实战指南:用浏览器 OAuth + PKCE 安全下载 ThreeUI Pro 组件源码 前端UI组件3D渲染【免费下载链接】threeuiOpen-source ThreeUI Community catalog with live interactive components and complete Community source.项目地址https://gitcode.com/gh_mirrors/th/threeui点击查看免费下载ThreeUI CLInpm 包名designcodeio/threeui-cli是 ThreeUI 为 Pro 成员提供的官方命令行工具用于把有权限entitled的组件实现源码下载到本地项目。它的核心设计是认证走浏览器、源码不进 npmnpm 上永远只有公开的 Community 组件Pro 组件源码必须通过浏览器 OAuth 授权后按需拉取。读完本文你将掌握该 CLI 的全部命令与参数、理解其基于 PKCE 的 OAuth 会话存储与自动刷新机制并能结合源码规避下载安装中的安全与冲突风险。为什么需要 CLIPro 源码不发布到 npmThreeUI 仓库README.md明确说明Pro 实现源码刻意不发布到 npm。公开的 React 组件库designcodeio/threeui只包含 50 个 Community 父组件与 141 个免费变体记录详见仓库根 README.md而 Pro 与 Beta 组件从公开包中移除。由此产生了一个分发问题如何让付费成员拿到授权源码同时保证源码不随 npm 包泄露ThreeUI 的答案是——用公开、独立的 CLI 包designcodeio/threeui-cli配合 OAuth 动态授权CLI 在浏览器中完成 ThreeUI 账号登录与授权consentCLI 携带 OAuth access token 调用受保护的组件 API按组件 ID 下载源码 bundle服务器端每次请求都校验账号的 entitlement是否有权访问该组件npm本身从不包含 Pro 源码。从源码结构看这个职责被拆分得非常清晰packages/cli/src/index.mjs 负责参数解析与命令调度packages/cli/src/oauth.mjs 负责完整的 OAuth 认证与会话管理packages/cli/src/install.mjs 负责组件下载与安全落盘。快速上手三个命令完成一次组件安装安装并添加第一个组件npx designcodeio/threeui-cli add cross-beam这是文档给出的最小用法npx会自动拉取并执行 CLI 包无需全局安装。add cross-beam的执行链路为读取本地已保存的 OAuth 会话若无有效会话则打开浏览器跳转 ThreeUI 登录与授权页面首次运行时必现浏览器回调后换取 access token并将其持久化到系统用户配置目录调用受保护 API 下载cross-beam的源码 bundle将文件安全地写入当前目录。对应实现位于 packages/cli/src/index.mjsgetAccessToken→downloadComponent→installBundle三步调用后终端会打印安装摘要包括组件标签与每个落盘文件的相对路径。登录与登出npx designcodeio/threeui-cli login npx designcodeio/threeui-cli logoutlogin会忽略已保存的会话、强制走一次全新浏览器登录源码中对应forceLogin: true见 oauth.mjslogout则直接删除本机保存的 OAuth 会话文件clearAuth见 oauth.mjs。如果你在多台机器或不同账号之间切换务必先logout再重新login。指定目录并强制覆盖npx designcodeio/threeui-cli add terrain-plume --dir ./src --force--dir把安装目标从当前目录改为./src--force允许覆盖项目中已存在且内容不一致的文件。关于--force的取舍下文冲突检测一节有详细说明。完整命令与选项清单CLI 的帮助文本直接定义在 packages/cli/src/index.mjs可用npx designcodeio/threeui-cli --help或-h查看命令作用add component-id认证并安装一个有权访问的组件源码 bundlelogin通过浏览器登录替换已保存的 OAuth 会话logout从本机删除已保存的 OAuth 会话选项作用默认值--dir path安装目标项目目录当前工作目录--force覆盖已存在的、内容有差异的文件不覆盖--no-open只打印登录 URL不自动打开浏览器自动打开--endpoint url覆盖组件 API 地址仅开发用https://threeui.com/api/pro-components--metadata url覆盖 OAuth 资源元数据地址仅开发用https://threeui.com/.well-known/oauth-protected-resource/api/mcp-h, --help显示帮助—-v, --version显示版本号—参数解析逻辑见 index.mjs--dir会立即resolve为绝对路径未知的-开头选项会直接抛错。另外add命令对组件 ID 有严格的格式校验必须匹配^[a-z0-9](?:-[a-z0-9])*$小写字母、数字与连字符否则报Invalid component ID见 index.mjs。这也是为什么示例中的cross-beam、terrain-plume都是这种短横线命名。认证机制纵深浏览器 OAuth 与 PKCE为什么用浏览器而非终端输入密码项目仓库根 README.md 一句话点明了设计目标authentication happens in the browser through ThreeUIs OAuth server认证发生在浏览器中通过 ThreeUI 的 OAuth 服务器完成。这样账号密码、二次验证等敏感流程全部落在官方网页上CLI 与 npm 包都不接触凭据。PKCES256挑战码oauth.mjs 中的createPkce()生成了标准 PKCE 对verifier48 字节随机数做 base64url 编码长度落在 RFC 7636 要求的 43–128 字符区间challenge对 verifier 做 SHA-256 后再 base64url 编码恰好 43 字符即S256方法。测试 cli.test.mjs 专门验证了这两条长度规则与两者不等的约束。PKCE 的作用是即使授权码在浏览器与回调之间被截获没有原始 verifier 也无法换取 token。动态客户端注册与回调服务器整个授权流程oauth.mjs大致如下资源服务器发现请求--metadata指定的受保护资源元数据读取authorization_servers[0]得到 OAuth 服务器地址OAuth 服务器发现拼接/.well-known/oauth-authorization-server校验authorization_endpoint、token_endpoint、registration_endpoint三个必备字段动态客户端注册CLI 无需预先注册而是向registration_endpointPOST 注册一个公共客户端token_endpoint_auth_method为none支持authorization_code与refresh_token两种授权类型本地回调CLI 在127.0.0.1:45987/callback起一个临时 HTTP 服务器见 oauth.mjs浏览器授权完成后重定向回该地址CLI 从 query 中提取code与state校验 state回调中的state必须与请求时生成的完全一致否则拒绝防 CSRF换取 token携带code、code_verifier、resource等参数 POST 到token_endpoint得到 access token 与 refresh token。回调服务器默认在 180 秒内未收到回调就会报Timed out waiting for browser authorization。如果你习惯用--no-open复制 URL 到别的浏览器/机器上完成授权需要注意这个超时窗口。会话存储owner-only 权限与原子写入CLI 把 OAuth 会话client_id、access_token、refresh_token、expires_at 与发现元数据持久化到操作系统用户配置目录文件名为auth.json。路径优先级由 oauth.mjs 中的defaultAuthPath()决定环境变量THREEUI_CONFIG_DIR指定目录下的auth.json最高优先级XDG_CONFIG_HOME下的threeui/auth.jsonmacOS~/Library/Application Support/threeui/auth.json其他平台~/.config/threeui/auth.json。写入采用严格的权限策略oauth.mjs父目录以0o700仅属主可读写执行创建先写临时文件再原子rename临时文件权限为0o600仅属主可读写。这是文档所述stores the resulting OAuth session … with owner-only permissions以仅属主权限保存会话的源码级落地——token 文件在 Linux/macOS 上不会暴露给同机其他用户。会话自动刷新getAccessTokenoauth.mjs按三级策略取 token直接复用access token 未过期且剩余有效期超过 60 秒TOKEN_SKEW_MS为时钟偏差预留的安全余量时直接返回静默刷新token 临近过期或已过期时用 refresh token 换新并把新会话写回磁盘若刷新得到的 token 不带新的 refresh token则沿用旧的很多授权服务器的轮换策略重新登录refresh token 过期或失效时自动回退到完整浏览器授权流程。所以日常使用中你基本感受不到过期只要登录过一次后续add大多静默完成无需反复打开浏览器。组件下载与安装源码 二进制资产的安全落盘下载协议downloadComponentinstall.mjs向--endpoint指定的 API 发起带Authorization: Bearer access_token的请求组件 ID 通过id查询参数传递。响应包含两部分source.filesUTF-8 文本源码数组每个文件含path与codeitem.assets二进制资产如图片、贴图清单CLI 会逐个以追加path参数的方式再次请求并保持原始字节不损坏。服务器返回错误时install.mjs会给出明确提示403表示账号无权访问该组件entitlement 校验失败401表示认证过期需要运行threeui login后重试。这也印证了仓库根 README 所述checks the account entitlement on every server request每次服务器请求都校验账号权限。路径安全拒绝穿越与绝对路径安装前install.mjs 对 bundle 中的每个文件路径做双重校验safeRelativePath拒绝空串、含\0、绝对路径、反斜杠、空段、.与..等一切可疑形式destinationPath在解析后再次确认目标仍落在目标目录内否则抛Refusing unsafe source path/Refusing source path outside the destination。测试 cli.test.mjs 用../secret、src/../secret、/absolute、src\\windows、src//file等样例验证了这些边界。换言之即使服务器被攻破返回恶意路径CLI 也不会把文件写到目标目录之外。冲突检测与 --force安装器install.mjs在写入前做三件事重复路径检测bundle 内出现两个落盘目标相同resolve归一化后的文件直接报错冲突检测默认开启目标位置已有文件且内容与将要写入的不同则拒绝写入并列出冲突文件清单提示Run again with --force to replace them内容相同则跳过目标文件存在但内容一致不会被视为冲突。--force的含义是覆盖内容不一致的既有文件测试 cli.test.mjs 验证了这一点默认模式下对已修改文件抛Refusing to overwrite加--force后成功替换。这保护了你在目标组件源码上的本地改动不被静默覆盖——如果你本地改过某个组件文件又想重装请三思再上--force。运行环境与工程配置packages/cli/package.json 定义了 CLI 的工程约束Node.js 版本engines要求node 20ESM 原生fetch、Response等能力依赖此版本入口type: modulebin字段把命令名threeui映射到./bin/threeui.mjs因此npx designcodeio/threeui-cli与npx threeui若已安装为依赖均可触发发布范围publishConfig.access为public且开启provenance供应链溯源files白名单只发布bin、src、README.md、LICENSE质量门禁prepack钩子会在打包发布前自动运行npm test保证发出去的版本必然通过测试。仓库的 scripts/library-package.test.mjs 还专门断言了 Pro 安装器使用公开包名designcodeio/threeui-cli防止发布流程误改包名。测试验证关键行为都有用例兜底packages/cli/test/cli.test.mjs 使用 Node 内置的node:test覆盖了五大行为PKCE 生成符合 S256 长度规范43–128 位 verifier、43 位 challenge源码路径必须相对且不可穿越OAuth 会话可完整写入并读回含 refresh 信息授权组件 bundle 与二进制资产完整落盘——测试用Uint8Array.from([0,1,2,255])断言二进制逐字节无损并断言每次 API 请求都带Bearer头默认拒绝覆盖已修改文件--force后放行。这些用例与本文前述的源码行为一一对应可以作为理解 CLI 行为边界的第一手参考。常见问题与排错建议基于源码行为给出几个高频场景的处置方式现象处置首次运行卡在Opening ThreeUI sign in浏览器未弹出网络受限环境可用--no-open终端会打印授权 URL手动复制到浏览器完成授权提示Your ThreeUI account cannot access this component403当前账号对该组件无 entitlement确认订阅状态或换成有权账号后login重试提示ThreeUI authentication expired; run threeui login and try again401直接执行npx designcodeio/threeui-cli login重建会话Refusing to overwrite existing files目标目录已有本地改动确认后加--force重跑或换--dir到新目录回调等待超时180 秒重新执行命令并在超时前完成浏览器授权检查回调端口127.0.0.1:45987未被占用想换机器/账号logout清除本机会话后重新login总结designcodeio/threeui-cli用一套紧凑的工程实现回答了付费源码如何安全分发的问题浏览器 OAuth PKCE 保证凭据不落地0o600权限与原子写入保护会话文件每次请求的服务端 entitlement 校验守住组件边界路径白名单与冲突检测防止误写误覆盖。三个模块index.mjs、oauth.mjs、install.mjs加起来不过两百多行配合 cli.test.mjs 的用例是学习CLI OAuth 安全下发内容这类场景的极佳范本。动手体验只需一行npx designcodeio/threeui-cli add cross-beam然后按--help探索其余选项。赞分享前端UI组件3D渲染【免费下载链接】threeuiOpen-source ThreeUI Community catalog with live interactive components and complete Community source.项目地址https://gitcode.com/gh_mirrors/th/threeui点击查看免费下载相关推荐DLSS Swapper3 步完成游戏 DLSS 版本切换不再等官方更新DLSS Swapper3 步完成游戏 DLSS 版本切换不再等官方更新 游戏更新后画面闪烁、帧数莫名下滑折腾一圈查不到原因多半是游戏自带的超采样插件版桌面应用游戏半年不更新用 DLSS Swapper 把超采样 DLL 换回最新版游戏半年不更新用 DLSS Swapper 把超采样 DLL 换回最新版 画面有拖影、伪影但游戏已经半年没发过一次更新——这种时候最让人憋屈的往往不是游戏桌面应用Puppeteer Browsers 的 install() 完全指南用代码与 CLI 下载安装 Chrome/Firefox 浏览器Puppeteer Browsers 的 install 完全指南用代码与 CLI 下载安装 Chrome/Firefox 浏览器 install 是 pu浏览器控制测试网页爬虫开发工具创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考