ThreeUI Community 开源版完全指南：免登录组件库的目录边界、本地运行与 npm 发布管线-育师

前端
UI组件
3D渲染

【免费下载链接】threeui

Open-source ThreeUI Community catalog with live interactive components and complete Community source.

项目地址：https://gitcode.com/gh_mirrors/th/threeui

ThreeUI Community 是 ThreeUI 的开源、免登录版本，它与主项目共用同一套应用外壳、布局、导航、浏览网格、搜索、主题、响应式行为、组件页面、实时渲染器、控件与变体选择器，唯一的"产品级"差异在于目录：Pro 与 Beta 组件被移除，而每个 Community 组件保留其全部免费变体与控件。本文基于本仓库 README.md 及其配套源码，系统讲解 Community 版的内容构成、本地运行方式、React 包安装方法、Pro 源码的 CLI 获取流程，以及仓库背后的同步与发布自动化管线，帮助你快速评估、运行并集成这套组件库。

ThreeUI Community 是什么：与主项目同构的免费开放版

官方 README 对其定位非常清晰：它使用与主项目（Pro 版）相同的应用外壳——布局、导航、浏览网格、搜索、主题、响应式行为、组件页面、实时渲染器、控件、变体选择器和源码标签页全部保留。也就是说，用户在该开源仓库中体验到的浏览与交互流程，与付费版本几乎一致，区别只在目录本身。

从目录构成看，仓库包含：

50 个 Community 父组件（parent components）；
111 条 Community 路由（routes，包含父组件及其变体页）；
141 条免费变体记录，外加23 个单例组件（singleton components），合计164 条浏览结果；
完整的 Community 实现源码与所需资源；
不含任何认证（authentication）、账户状态（account state）、结账运行时（checkout runtime）、Pro 实现或 Beta 实现；
界面中的Get Pro入口指向https://threeui.com/pricing。

上述数字可以直接在仓库内的同步报告 public/community-sync-report.json 中核对：communityParents为 50、communityRoutes为 111、communityVariants为 141，同时excludedProParents为 45、excludedBetaParents为 2，说明这次快照中主项目共排除了 45 个 Pro 父组件与 2 个 Beta 组件。

从 src/index.ts 的导出列表可以看到 Community 组件覆盖的广度：从落地页类（KageLandingPage、CompleteShelfLandingPage、BestsellersBookShowcase、SylvaHero、MengToSketchbookLandingPage），到背景与场域类（ConstellationField、StructureFlowCollection、PortalFieldCollection、LiquidFormBackground、WarpFieldBackground），再到按钮与交互组件（CircleButtons、LiquidMetalButton、TactileButton、PlasmaButton、AnimatedTopDock）、文字动画类（ArticleHeadings、TypographyVortexCanvas、SemanticBloom）以及 Three.js 场景类（LandscapeScene、JapaneseTowerLandscape、BookshelfScene、TempleNightScene、SylvaLivingWorldScene）等。

公开边界（Public Boundary）：Community 与 Pro/Beta 的划分机制

Community 版的目录边界并非简单删文件，而是由一整套"公开边界"机制保证的。核心体现在 scripts/sync-community-from-main.mjs 与测试 scripts/public-boundary.test.mjs 中：

混级访问组件只保留 Community 选项：例如GlobeCollection只导出energy-orb变体，SparkBadge只导出badge变体，SylvaLivingWorldScene只导出living-green，TempleNightScene只导出temple-night。测试通过检查export type ...Variant =联合类型仅有一个成员来强制这一契约（见 public-boundary.test.mjs）。
渲染器 CSS 剔除 Pro/Beta 选择器：同步脚本从主项目样式表中截取 Community 专属的 CSS 片段（.threeui-background、.japanese-tower-landscape、.liquid-metal-button、.spark-badge等），并断言诸如mechanical-keyboard、terrain-plume、sunset-valley等被排除选择器不会出现。
公开外壳不含认证与私有目录运行时：测试扫描src/下所有文件，确认不存在AuthProvider、AccountButton、OAuthConsent、Supabase 客户端、Stripe checkout、sf-*.woff2字体等主项目私有实现（见 public-boundary.test.mjs）。

同时 scripts/audit-public.mjs 会对整个仓库做一次公开审计：不允许符号链接、.env文件、绝对用户路径、私钥材料以及疑似敏感赋值，保证该仓库可以安全公开。

本地运行与构建

启动开发服务器

npm install npm run dev

npm run dev对应 package.json 中的vite脚本，即使用 Vite 启动本地开发服务器，可以直接在浏览器中体验完整的 Community 目录、实时渲染器与控件。

运行完整的发布边界、类型与生产构建检查

npm run build

npm run build是一条完整的质量门禁链（见 package.json）：

"build": "npm run test && npm run build:site && npm run build:lib"

它依次执行：

npm run test：运行 Node 原生测试，覆盖 scripts/community-sanitizers.test.mjs、scripts/public-boundary.test.mjs、scripts/library-package.test.mjs、scripts/prepare-community-release.test.mjs 以及 packages/cli/test/cli.test.mjs；
npm run build:site：先执行tsc --noEmit类型检查与audit:public公开审计，再执行vite build构建站点；
npm run build:lib：生成库入口 src/index.ts（由 scripts/generate-library-entry.mjs 生成）、使用 vite.lib.config.js 构建 ES 库、用tsc -p tsconfig.lib.json生成类型声明，并通过 scripts/copy-library-assets.mjs 拷贝运行时资源。

其中vite.lib.config.js将react、react-dom、three、three128、three165设为外部依赖，并以preserveModules方式保留模块结构，使每个组件都能被独立按需引入。

安装 React 包

基础安装与导入

从 npm 安装公开的 Community 组件库：

npm install @designcodeio/threeui

然后导入组件与共享样式：

import { AtTheHorizon } from "@designcodeio/threeui"; import "@designcodeio/threeui/style.css"; export function Hero() { return <AtTheHorizon />; }

最小化开发导入图：组件子路径

为了得到最小的开发期 import 依赖图，可以改用组件子路径导入：

import { AtTheHorizon } from "@designcodeio/threeui/components/AtTheHorizon";

这一能力来自 package.json 中的exports映射："./components/*"指向./lib-dist/package-components/*.js，而"./style.css"指向./lib-dist/style.css，"./assets/*"指向./lib-dist/assets/*。生成这些独立入口的正是 scripts/generate-library-entry.mjs：它从 src/data/shaders.tsx 的目录导入中解析出所有渲染器导出，在 src/package-components 下为每个组件生成转发文件。

组件入口也支持其他主流包管理器，站点内的安装步骤组件 src/components/InstallationSteps.tsx 提供了 npm、pnpm、bun、yarn 四种命令：

npm install @designcodeio/threeui pnpm add @designcodeio/threeui bun add @designcodeio/threeui yarn add @designcodeio/threeui

版本与依赖要求

从 package.json 可以确认当前包版本为0.3.0，其peerDependencies要求：

react与react-dom：>=18 <20；
three：>=0.149 <1。

此外包内部依赖两个固定版本的三维运行时：three128（three@0.128.0）与three165（three@0.165.0），用于不同组件对旧/新 Three.js API 的兼容需要（如 src/shaders/bookshelf/three165 下的辅助模块）。

渲染完整 HTML 文档的组件与运行时资源

需要注意：渲染完整 HTML 文档的组件（例如落地页、SparkBadge、LandscapeScene、JapaneseTowerLandscape等 iframe 类渲染器）会期望它们的运行时文件位于与 ThreeUI 预览相同的根相对 URL 上。安装后需要从

node_modules/@designcodeio/threeui/lib-dist/assets/

将所需文件复制到你自己应用的 public 目录；如果组件支持，也可以通过覆盖组件的sourceUrl或assetBaseUrlprop 来指定位置。

这些运行时文件由 scripts/copy-library-assets.mjs 在构建时从public/拷贝到lib-dist/assets/，包括japanese-tower.html、landscape.html、spark-badge.html、synthralos-halftone.html、landing-pages/与sketchbook/目录（若目录中存在hypnotic-loops组件还会包含hypnotic-loops.html）。

包发布形态验证

scripts/library-package.test.mjs 锁定了包的发布契约：@designcodeio/threeui为公开包（publishConfig.access: "public"）、提供 ESM、类型声明、CSS 与资源导出；同时验证 CLI 包@designcodeio/threeui-cli也是公开包且bin.threeui指向./bin/threeui.mjs。此外 scripts/package-install-smoke.mjs 会在发布前模拟一次匿名环境安装：清空所有 npm 认证相关环境变量，npm pack打包后在一个全新临时目录中安装 tarball 并验证根入口与子路径@designcodeio/threeui/components/CloudField均可正常解析——这正是 README 所述"匿名安装冒烟测试"的实现。

Pro 源码访问：通过 threeui-cli 下载受限源码

为什么 npm 里没有 Pro 源码

README 明确指出：Pro 实现源码刻意不发布到 npm。活跃的 ThreeUI Pro 会员通过浏览器认证，然后使用公开 CLI 下载其有权获取的源码包：

npx @designcodeio/threeui-cli add cross-beam

CLI 的完整命令面

CLI 的帮助文本（见 packages/cli/src/index.mjs）定义了三条命令：

npx @designcodeio/threeui-cli login npx @designcodeio/threeui-cli logout npx @designcodeio/threeui-cli add terrain-plume --dir ./src --force

可用的选项包括：

选项	作用
`--dir <path>`	指定目标项目目录（默认当前目录）
`--force`	允许替换已存在且内容有差异的文件
`--no-open`	只打印登录 URL，不自动打开浏览器
`--endpoint <url>`	覆盖组件 API（仅开发用）
`--metadata <url>`	覆盖 OAuth 资源元数据（仅开发用）
`-h, --help`	显示帮助
`-v, --version`	显示版本

CLI 还会校验组件 ID 必须匹配^[a-z0-9]+(?:-[a-z0-9]+)*$（见 packages/cli/src/index.mjs），并对未知选项直接报错。

OAuth with PKCE 的实现细节

CLI 的认证实现位于 packages/cli/src/oauth.mjs，完整呈现了 README 描述的安全模型：

动态客户端注册：通过 OAuth 资源元数据https://threeui.com/.well-known/oauth-protected-resource/api/mcp发现授权服务器，再在registration_endpoint注册一个仅允许authorization_code与refresh_token授权类型的公开客户端（token_endpoint_auth_method: none）；
PKCE (S256)：每次登录生成 48 字节随机 verifier 并做 SHA-256 challenge，配合state防 CSRF；
本地回环回调：在127.0.0.1:45987/callback起一个临时 HTTP 服务器接收授权码，超时 180 秒；
会话持久化：令牌写入操作系统用户配置目录（~/.config/threeui/auth.json或 macOS 的Library/Application Support/threeui/auth.json），目录权限0o700、文件权限0o600，即"owner-only permissions"；
可刷新会话：access token 过期前（提前 60 秒）直接用 refresh token 续期；refresh token 失效时才回退到浏览器重新登录；
账号权益校验：每次服务器请求都携带Authorization: Bearer <token>；返回 403 表示"账号无权访问该组件"，401 表示"认证过期，请先运行 threeui login"（见 packages/cli/src/install.mjs）。

拒绝覆盖已更改文件

下载与落盘逻辑在 packages/cli/src/install.mjs 中：所有 bundle 内路径都要经过safeRelativePath校验（拒绝绝对路径、..、空段与 NUL 字符），且解析后的目标必须位于目标目录内，防止路径逃逸；默认（不带--force）情况下，若目标文件已存在且内容与 bundle 不一致，会抛出 "Refusing to overwrite existing files" 并列出冲突文件，要求追加--force才允许替换——这正是 README 所述"refuses to overwrite changed project files unless--forceis supplied"的源码实现。

Community 同步与自动化发布管线

从主项目快照同步 Community 子集

该仓库本身是独立运行的。维护者可以单独保存一份主项目快照，然后执行：

npm run sync:community -- /path/to/main-threeui

（对应 package.json 中的node scripts/sync-community-from-main.mjs；也可以设置THREEUI_SOURCE_ROOT环境变量代替路径参数。）

同步脚本的行为与 README 描述完全一致：

fail closed：要求传入快照路径并读取其inventory/source-code.json，否则直接抛错；同步前还会用 Vite 的ssrLoadModule加载主项目 src/data/shaders.tsx，只保留status !== "beta"且非 Pro 的组件（见 sync-community-from-main.mjs）；
过滤 Pro 与 Beta 后再生成公开导入图：重写src/data/shaders.tsx，把渲染器统一命名为CommunityRendererN，并清除access、status等受限字段；
保留所有免费元数据与选项：变体、控件（含variantControlKeys）逐一保留，远端缩略图/预览图统一重写到https://threeui.com的公开 URL；
移除受限字体资源：同步时明确排除sf-bold/light/medium/regular/semibold.woff2等受限字体（见 sync-community-from-main.mjs）；
对混级访问组件做元数据改写：例如energy-orb固定为 "Energy Orb" 变体、sylva-hero固定为 "Living Green"、temple-night固定为 "Procedural Kyoto mountain temple world"。

同步最终写入三份关键产物：

public/community-sync-report.json —— 组件/变体/控件计数与逐组件 parity 报告；
public/source-code.json —— Code 标签页使用的 Community 源码包（含每个文件的sha256与sourceCommit）；
src/data/shaders.tsx —— 仅含 Community 的目录与渲染器导入。

无操作同步与版本发布策略

README 描述了主项目侧的自动化：私有 ThreeUI 仓库在每次成功推送到main后运行该同步；no-op 同步（内容无变化）不会触发发布，有变化则更新automation/community-sync分支并在这里开一个评审 PR。

发布类型的推断逻辑实现在 scripts/prepare-community-release.mjs：

以component:<id>、variant:<id>:<vid>、control:<id>:<key>等 token 描述"公开表面"（public surface）；
对比同步前后的表面集合：有移除 → major；有新增（新组件、变体或控件）→ minor；仅源码兼容性变化 → patch；
也支持用--type <patch|minor|major>显式指定，但若低于推断级别会直接报错拒绝；
新版本号写入 package.json 与 package-lock.json 的根记录，并通过GITHUB_OUTPUT供 CI 消费。

合并带版本的同步 PR 后，会通过npm trusted publishing with provenance发布新包。公开工作流在发布前还会执行：一次干净的构建（clean build）、边界审计（boundary audit）、包创建（package creation）与匿名安装冒烟测试（anonymous installation smoke test，即上文所述的 scripts/package-install-smoke.mjs）。

此外，Pro 安装器（@designcodeio/threeui-cli）是单独版本化、单独发布的：Pro 组件内容的变更不需要触发 CLI 发版，两者解耦。

许可证与第三方资源

本仓库的授权情况在 README 中明确列出，并在 ASSET-LICENSES.md、FONT-LICENSES.md 与 THIRD_PARTY_NOTICES.md 中有详细记录：

MIT：应用代码、Community 组件代码、ThreeUI 自创的 Community 图像；
SIL Open Font License 1.1：捆绑的开源字体（例如 public/sketchbook 下的instrument-serif.woff2、newsreader.woff2，以及 src/shaders/fonts 下的fragment-mono.woff2等）；
MIT：捆绑的 Three.js 运行时文件（如 public/landing-pages/inner-green-assets/three.min.js）；
不在本仓库分发范围内：从https://threeui.com远程加载的目录缩略图与预览图。

若在自有项目中引用这些资源，建议同时查阅上述三份许可证文档，按各自条款合规使用。

小结

从 README.md 及其配套实现可以看出，ThreeUI Community 并不仅仅是一个"去掉付费内容的副本"：它以同步脚本、公开边界测试、包构建管线、CLI 认证下载和自动化版本发布构成了一套完整的开源发布体系。你可以通过npm install @designcodeio/threeui直接把它集成进自己的 React 应用（注意react >=18 <20与three >=0.149 <1的 peer 依赖，以及完整 HTML 渲染器组件的lib-dist/assets资源拷贝）；需要更深入地研究组件实现时，可以直接阅读 src/shaders 下的渲染器源码、src/data/shaders.tsx 的目录元数据，以及 public/source-code.json 中带哈希校验的源码快照。