AlbertAZ1992/every-qrcode
AlbertAZ1992/every-qrcode has 31 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 16:57 UTC. Last push 2026-10-21.
实测星标增长
- 24小时
- 0
- 7天
- 更新延迟
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Open-source React QR code generator and Web Component with deterministic 3D Tree and Terrain effects, powered by WebGPU.
网站与应用README.zh-CN.md
原文Every QR Code
English | 简体中文
一个开源的 React QR Code 生成器和 Web Component:把 URL 变成确定性、可扫描的 3D 世界。 你可以选择 Tree 或 Terrain,再让它变回对应的标准二维码。
在线体验 · React npm · Web Component npm · 参与贡献
pnpm add @every-qrcode/react
Tree

Terrain

Every QR Code 可以把一个 URL 变成确定性、可扫描的 3D 世界。相同的标准化身份、模型和 generator version 会产生相同的 QR 矩阵和视觉基因。你可以在 Tree、Terrain 和标准二维码 之间切换,而目标链接保持不变。
你可以使用 React 组件、与框架无关的 Web Component,或者更底层的 TypeScript 和 WebGPU 包。所有渲染都在浏览器本地完成,不包含遥测,也不会调用服务器。
为什么使用 Every QR Code?
- 从设计上保证可扫描——每个世界都可以变回对应的标准 QR 矩阵。
- 带版本的视觉身份——已经保存的世界继续使用创建它时的生成器。
- 两个懒加载 3D 模型——只在选择 Tree 或 Terrain 时加载对应的 shader bundle。
- 支持 React 和 Web Components——在不同前端技术栈中使用同一套渲染器。
- WebGPU 降级方案——不支持 WebGPU 时显示静态、可扫描的 SVG QR Code。
- 保护隐私——生成过程完全在本地运行,不包含分析或网络请求。
React QR Code 组件
import { EveryQRCode } from "@every-qrcode/react";
export function WebsiteIdentity() {
return <EveryQRCode url="https://example.com" />;
}
组件默认使用 Tree、站点级身份、优先显示 3D 模型,并支持点击显示二维码。需要时可以使用
model="terrain"、initialView="qr" 或 identityScope="url"。
QR Code Web Component
pnpm add @every-qrcode/web-component
import "@every-qrcode/web-component/auto";
<every-qr-code url="https://example.com"></every-qr-code>
Packages
| Package | 用途 |
|---|---|
@every-qrcode/react |
React 组件和带类型的展示 API |
@every-qrcode/web-component |
原生 Custom Element,可选择自动注册 |
@every-qrcode/core |
URL 标准化、Link DNA 和标准 QR Code 生成 |
@every-qrcode/renderer-webgpu |
懒加载的 Tree 和 Terrain WebGPU 渲染器 |
产品通常只需要安装 React 或 Web Component 包。它们会自动引入共享的 core 和 renderer。
模型和身份
model="tree"渲染确定性的 Tree 形态。model="terrain"渲染确定性的 Terrain 形态。identityScope="site"是默认值,同一主机名下的所有路径共享一个身份。identityScope="url"会把完整的标准化 URL 纳入身份。- 两个模型最终都会变回同一个标准 QR 矩阵。
可复现世界:generator v1 和 v2
Generator version 是一套“绘制世界的配方”,不是 npm 包版本:
相同 URL + generator v1 → 原来的世界
相同 URL + generator v2 → 使用新配方生成的新世界
新的 npm 包可以同时包含 v1 和 v2。升级 npm 包不会自动把已经保存的 v1 世界变成 v2。
把版本和 URL 一起保存
如果一个世界需要保存或分享,请在创建时记录当前 generator version:
import { CURRENT_GENERATOR_VERSION, EveryQRCode } from "@every-qrcode/react";
const savedWorld = {
generatorVersion: CURRENT_GENERATOR_VERSION,
url: "https://example.com",
};
<EveryQRCode generatorVersion={savedWorld.generatorVersion} url={savedWorld.url} />;
Web Component 使用相同规则,对应的属性是 generator-version="1"。
- 不需要保存世界?可以不传版本,直接使用当前生成器。
- 正在迁移没有版本的旧数据?一次性把缺失版本设为
1。 - 正在读取已保存的世界?把保存的版本原样传回组件。
- 当前包不支持这个世界的版本?请升级包;组件不会偷偷替换成另一套生成器。
这次升级增加了什么?
- React 新增公开的
generatorVersion属性,Web Component 新增generator-version属性。 - 为 seed model、Tree/Terrain 几何和 shader 建立冻结的 v1 路径。
- 增加 golden fingerprint 测试,未来改动如果意外改变 v1,测试会失败。
- Studio 分享链接和 Gallery 数据保存 generator version,旧数据统一迁移为 v1。
未来加入 v2 时,包里会新增一套独立的 v2 实现,并让新建世界默认使用 v2。已经记录版本 1 的世界仍然使用保留下来的 v1 实现。
Studio 会把 generator version 和 URL、模型、主题一起保存在分享 链接中,因此已保存的链接会继续使用创建它时的视觉算法。
内部结构可以查看 package architecture 和 technical architecture。如果要添加新的懒加载模型,请查看 renderer model guide。
参与贡献
你不需要一次完成整个 3D 模型。视觉参考、几何草图、确定性算法、WGSL shader、测试和文档 都可以成为一次有效贡献。
请先阅读 CONTRIBUTING.md,选择一个足够小的切入点。当前公开的模型路线图 包括 Hokusai Waves、Crystalline 和 Mechanical。
浏览器支持
交互式 3D 视图使用 WebGPU。如果 WebGPU 初始化失败,React 和 Web Component 会显示静态 SVG QR Code,确保链接仍然可以扫描。
本地开发
需要 Node.js 22+ 和 pnpm 10+。
pnpm install
pnpm dev
发布前运行:
pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm format:check
维护者通过 GitHub Release 工作流 发布 npm 包,并使用 npm Trusted Publishing,不在 GitHub 中长期保存发布 token。