Git City：用代码构建的 3D 像素都市，每个开发者都是一座地标

核心问题：如果枯燥的代码提交记录变成了可见的 3D 实体建筑，我们的技术档案会呈现出怎样的城市景观？

答案是：它会变成一座充满生机的像素都市。Git City 将 GitHub 个人资料转化为独特的像素艺术建筑，通过高度、宽度、亮度的映射，让开发者的贡献历史变得触手可及。这不仅仅是一个可视化项目，更是一个融合了 3D 渲染技术、社交互动与游戏化思维的创新平台。

一、 项目概览：当代码成为城市的基石

本段核心问题：Git City 究竟是什么？它如何重新定义开发者的身份展示？

Git City 是一个交互式的 3D 城市模拟平台，它将每一位 GitHub 用户的个人主页转化为一座独一无二的建筑。在这个虚拟城市中，代码贡献不再只是枯燥的绿色方格图，而是拔地而起的高楼大厦。贡献越多，楼层越高；仓库越广，地基越宽。

图片来源：Unsplash – 城市景观示意

该项目由开发者 Samuel Rizzon 构建，通过 Next.js 16 和 Three.js 技术栈实现了在浏览器端的流畅 3D 体验。用户可以在城市中自由飞行，查看其他开发者的“建筑”，甚至对自己的建筑进行装修和定制。

1.1 核心理念：可视化技术档案的价值

在传统的开发者社交网络中，我们习惯于通过简历、代码仓库列表或者静态的贡献图表来了解一个人。Git City 打破了这种二维平面的限制。它构建了一个“赛博朋克”式的社交空间，在这里，你可以直观地看到一个开发者的影响力——那是一座灯火通明的摩天大楼，还是一座精致的小屋。

这种可视化的价值在于直觉性。不需要阅读复杂的图表，只需一眼扫过天际线，你就能识别出社区中的核心贡献者。正如社区用户所言，这让人联想到威廉·吉布森笔下对“赛博空间”的描述，将抽象的数据具象化为空间实体。

二、 建筑映射逻辑：数据如何决定形态

本段核心问题：GitHub 上的各项数据指标是如何具体转化为建筑特征的？

每一座建筑的生成都严格遵循一套基于 GitHub 数据的映射规则。这些规则确保了建筑的独特性，同时也保证了视觉表现与数据实质的统一。系统采用实例化网格和细节层次系统进行渲染，既保证了近处建筑的细节丰富度，又优化了远距离观看时的性能。

以下是具体的映射机制：

数据指标	建筑特征影响	具体示例
贡献数量	决定建筑高度	1,000 次提交对应更高的楼层数，形成摩天大楼
公开仓库	决定建筑宽度	仓库数量多，建筑的底座面积更大，显得稳重
获得星标	决定窗户亮度	星标多，窗户发出的光芒更亮，更显眼
近期活跃度	决定窗户发光模式	近期活跃，窗户呈现出独特的呼吸/闪烁光效

2.1 技术实现的细节与场景

场景示例：
假设一位开发者近期被提升为管理层，他的代码提交量可能会下降。在 Git City 中，这直观地表现为他的建筑“停止生长”或者相对于周围持续增长的建筑显得不再那么突出。社区评论中有人戏称：“你甚至可以看出有些人是什么时候升职做经理的”，这正是数据可视化带来的独特叙事能力。

技术反思：
这种基于实例化网格的渲染方式是项目能够流畅运行的关键。如果对每个建筑都独立建模，浏览器将不堪重负。通过 LOD 系统，远处的建筑会被简化为低多边形模型，只有当用户驾驶飞机靠近时，才会加载精细的窗户动画和光影效果。这种“按需加载”的工程思维，与我们现在的前端性能优化理念不谋而合。

三、 核心功能与用户体验

本段核心问题：除了观看建筑，用户还能在这个平台上做什么？

Git City 不仅仅是一个观赏性的模型展，它构建了一套完整的互动生态。从飞行探索到社交互动，再到个人成就系统，每一个环节都在增强用户的参与感。

3.1 自由飞行与探索模式

用户可以驾驶一架像素风格的小飞机，在城市上空自由穿梭。这种体验让人联想到经典的模拟飞行游戏。通过平滑的相机控制，你可以飞临任何一座建筑的顶端，俯瞰整个城市的纹理。

图片来源：Pexels – 飞行探索示意

用户反馈与改进空间：
在移动端体验上，触控操作在点击高大建筑时存在一定的优化空间。这提示我们在开发 WebGL 重度应用时，PC 端与移动端的交互逻辑需要分别进行针对性设计。此外，社区中甚至有人提出了极具趣味性的建议：增加碰撞检测，允许飞机撞击建筑并造成“损坏”，唯有通过提交新代码才能修复。这种想法虽然疯狂，却深刻揭示了开发者对“代码即力量”的渴望。

3.2 个人主页与成就系统

每个开发者都有独立的个人资料页面，详细展示了他们的统计数据、成就徽章和热门仓库。成就系统是激励用户参与的重要机制，涵盖了贡献量、星标数、仓库数以及推荐好友等多个维度。

功能亮点：

• 建筑定制：用户可以认领自己的建筑，并在商店购买装饰品（如皇冠、光环、屋顶特效、面部装饰等）来个性化外观。
• 社交互动：支持向其他开发者发送称赞、赠送物品，以及查看实时的活动动态流。
• 对比模式：这是一个极具杀手潜质的功能。将两名开发者并排对比，通过建筑的高度差和宽度差，直观地展示两人的技术影响力差异。
• 分享卡片：生成风景或故事格式的分享图片，便于在社交媒体传播。

3.3 商业化尝试：聪明的盈利模式

项目引入了基于 Stripe 的支付系统，允许用户购买装饰品。这种模式非常聪明，它没有破坏核心的开源精神，而是通过提供个性化增值服务来获取收入。对于那些希望自己的建筑在人群中脱颖而出的开发者来说，这是一种可以接受且有趣的付费点。

四、 技术栈深度剖析

本段核心问题：如何在 Web 端构建一个高性能、可扩展的 3D 实时渲染应用？

Git City 的技术选型非常现代化，代表了当前 Web 开发的前沿趋势。它选择了 Next.js 16 作为全栈框架，利用其最新的 App Router 和 Turbopack 打包工具，极大地提升了开发效率和应用性能。

图片来源：Unsplash – 技术栈示意

4.1 核心技术组件

1. 3D 引擎：

   • 使用了 Three.js 作为底层 WebGL 库。
   • 通过 react-three/fiber 将 Three.js 的命令式语法转换为 React 的声明式组件，使得 3D 场景的管理变得像写普通 DOM 结构一样简单。
   • 辅助库 drei 提供了大量实用的助手工具和抽象，如相机控制、加载器等，进一步降低了开发门槛。

2. 后端与数据库：

   • 使用 Supabase 提供后端服务。这不仅包括 PostgreSQL 数据库，还集成了 GitHub OAuth 认证和行级安全策略。这意味着数据的安全性直接在数据库层面得到了保障，而非仅仅依赖应用层逻辑。

3. 样式与字体：

   • Tailwind CSS v4 负责样式的快速构建。
   • 字体选择了 “Silkscreen”，这是一款像素风格的字体，完美契合项目的整体美术风格，增强了沉浸感。

4.2 开发实录：21,000 行代码的诞生

本段核心问题：如何在极短时间内构建如此复杂的系统？

这可能是该项目最令人震惊的部分：作者在 4 天内编写了约 21,000 行代码。这揭示了现代 AI 辅助编程的巨大潜力。作者在回复中提到，他的工作流是 “Claude Code + VSCode + Me”。

作者反思与见解：
这不仅仅是速度的问题，更是“Vibe Coding（氛围编程）”的体现。在这种模式下，开发者更像是一个架构师和指挥官，而 AI 则是执行具体逻辑的工兵。

• 效率的质变：传统的开发流程中，配置 Webpack、调整相机参数、编写 SQL 语句等琐事会消耗大量时间。而在 AI 辅助下，开发者可以专注于核心业务逻辑——即“建筑如何映射数据”以及“用户如何交互”。
• 质量控制：虽然代码生成速度极快，但 Reddit 社区也指出了移动端适配等问题。这说明 AI 生成的代码虽然骨架结实，但在细节打磨和边缘情况处理上，依然需要人类的经验介入。这也验证了“Human-in-the-loop”（人机回环）的重要性——AI 可以造出一座城，但只有人类能让这座城宜居。

五、 部署与运行指南

本段核心问题：普通开发者如何本地运行或二次开发这个项目？

作为一个开源项目（AGPL-3.0 许可证），Git City 允许任何人克隆、修改和部署。以下是详细的启动步骤：

5.1 快速启动步骤

1. 克隆仓库：
   首先，将项目代码克隆到本地。

   git clone https://github.com/srizzon/git-city.git
   cd git-city
   

2. 安装依赖：
   使用 npm 安装项目所需的依赖包。

   npm install
   

3. 环境配置：
   复制示例环境文件，并填入必要的密钥。你需要 Supabase 项目地址和密钥，以及 Stripe 的 API 密钥。

   cp .env.example .env.local
   # 在 .env.local 中填写 Supabase 和 Stripe 的相关配置
   

4. 运行开发服务器：
   启动本地开发环境。

   npm run dev
   

   随后，浏览器访问 http://localhost:3001 即可看到你本地的 Git City。

5.2 许可证说明

项目采用 AGPL-3.0 许可证。这意味着你可以自由使用和修改代码，但如果你将修改后的版本通过网络向公众提供服务，你必须公开你的源代码。这是对开源精神的一种强力保护，确保了社区能够持续从改进中受益。

六、 社区回响与未来想象

本段核心问题：业界对这个项目有何反应？它还能如何进化？

自发布以来，Git City 在 Reddit 等技术社区引发了热烈讨论。大多数评论集中在“这太酷了”、“终于有人做出了赛博朋克式的 GitHub”等赞美上。甚至有用户表示，这让他想起了 2000 年代中期的游戏《Coke Music》或《SimCopter》，这种怀旧感与现代技术的结合产生了奇妙的化学反应。

6.1 用户洞察

• “经理楼”现象：有用户发现，可以通过建筑的高度变化判断开发者的职业轨迹。这种无意的叙事功能为项目增添了社会学意义。
• 主流化潜力：评论指出，如果这种模式被移植到 Twitter、Facebook 或 Reddit 等社交平台，可能会成为主流。试想一下，如果 Twitter 的个人主页是一座由推文数量决定高度的城市，那将是一种怎样的体验？
• 互动性需求：用户渴望更深度的交互，如点击窗户查看具体的提交记录，或者前面提到的“飞机撞击”功能。这表明用户不仅仅满足于“看”，更希望“玩”。

6.2 独特的见解：可视化的下一个前沿

Git City 的成功不仅仅是技术的成功，更是概念的胜利。它证明了在 Web 3.0 时代，我们对于身份的展示可以更加立体和多元化。

• 从平面到空间：互联网早期的个人主页是纯文本，后来变成了多媒体卡片。现在，Git City 预示着“空间化主页”的可能。
• 数据的地标化：将数据转化为地标，让原本冷冰冰的数字拥有了物理世界的属性（高度、体积、光影），这极大地增强了数据的情感共鸣。

图片来源：Unsplash – 数据连接与未来

七、 实用摘要与操作清单

为了方便各位开发者快速上手或借鉴，以下是本文内容的精华摘要。

7.1 实用摘要

Git City 是一个将 GitHub 资料可视化为 3D 像素建筑的开源项目。它利用 Next.js、Three.js 和 Supabase 构建了一个可交互的城市环境，通过建筑的高度、宽度和亮度映射用户的贡献、仓库和星标。项目不仅提供了飞行探索、建筑定制等娱乐功能，还探索了 AI 辅助编程（Vibe Coding）在快速构建复杂系统中的应用。其 AGPL-3.0 开源协议鼓励社区在此基础上进行二次创新。

7.2 操作清单

如果你想基于此项目进行学习或开发，请执行以下步骤：

• [ ] 环境准备：确保本地安装了 Node.js 和 Git。
• [ ] 代码获取：git clone https://github.com/srizzon/git-city.git。
• [ ] 依赖安装：运行 npm install。
• [ ] 服务配置：注册 Supabase 账号并创建项目，获取 API URL 和 Key；注册 Stripe 账号（如需测试支付）。将这些信息填入 .env.local。
• [ ] 启动项目：运行 npm run dev 并访问 localhost:3001。
• [ ] 代码研读：重点关注 components/ 目录下的 Three.js 组件逻辑，以及 app/ 目录下的 Next.js 路由结构。
• [ ] 二次开发尝试：尝试修改建筑映射规则（例如，将 Issues 数量映射为建筑的颜色），体验数据可视化的乐趣。

---

一页速览

项目名称：Git City
核心价值：将 GitHub 贡献记录转化为 3D 像素城市，实现技术档案的立体化与游戏化。
技术栈：Next.js 16 (App Router), Three.js (React Three Fiber), Supabase, Tailwind CSS v4.
关键特性：

• 数据映射：高度=贡献，宽度=仓库，亮度=星标。
• 互动：飞行模式、建筑定制、开发者对比。
• 开发模式：AI 辅助极速开发（4天/2.1万行代码）。
  开源协议：AGPL-3.0（需开源二次开发版本）。
  适用人群：前端工程师、WebGL 爱好者、开源项目维护者。

---

常见问答 (FAQ)

Q1：Git City 是如何保证 3D 场景在浏览器中的流畅运行的？
项目使用了 Three.js 的 Instanced Mesh 技术来处理大量重复的建筑结构，并引入了 LOD（Level of Detail）系统。这意味着远处的建筑使用简化模型，近处的才使用精细模型，从而大幅降低 GPU 负载。

Q2：我的 GitHub 数据会被存储吗？是的，存储在哪里？
是的，项目使用 Supabase（基于 PostgreSQL）来存储用户数据。Supabase 还提供了 GitHub OAuth 认证，确保只有用户本人可以修改自己的建筑设置。

Q3：为什么选择 AGPL-3.0 许可证？
AGPL-3.0 是一个严格的开源协议。它规定，任何对代码进行修改并将其作为网络服务提供的开发者，都必须公开其修改后的源代码。这确保了社区贡献能够回馈给所有用户。

Q4：我可以使用其他 3D 引擎来实现类似功能吗？
当然可以。虽然本项目使用了 Three.js，但核心逻辑是数据到几何体的映射。你完全可以使用 Babylon.js 或 PlayCanvas 等其他 Web 3D 引擎，甚至可以在游戏引擎（如 Unity/Unreal）中实现类似的可视化。

Q5：项目支持移动端访问吗？
支持，但体验尚需优化。根据社区反馈，移动端的飞行控制和点击交互在某些情况下（如点击高楼）体验不如 PC 端顺滑，这是 Web 3D 应用在移动端普遍面临的挑战。

Q6：什么是“Vibe Coding”，在这个项目中体现了什么？
“Vibe Coding” 在此项目中指代利用 AI（如 Claude Code）辅助进行高强度、快速的代码生成。它体现了开发者从“写代码”向“指挥写代码”的角色转变，极大地缩短了从创意到原型的周期。

Q7：如何自定义我的建筑外观？
你需要登录并“认领”你的建筑。之后，你可以通过平台内置的商店（需要付费或可能通过活动获得）购买皇冠、光环等装饰品，直接在 3D 场景中应用到你的建筑上。

Q8：这个项目可以用于非 GitHub 的数据可视化吗？
完全可以。其架构具有通用性。只要将数据源替换（例如 Twitter 的推文数、Facebook 的互动数），并调整映射规则，就可以轻松将其改造为“Twitter City”或任何其他形式的数据城市。