企业官网建设流程全解析

• 游戏开发
• 教育
• 前端
• 后端

CodeCombat 是一个以"游戏化编程学习"为核心的多人在线编程游戏开源项目——玩家通过编写真实代码（Python、JavaScript 等）操控游戏角色闯关，在战斗与解谜中掌握编程技能。本文以仓库根目录 README.md 为主体脉络，结合 package.json、server_config.js、webpack.base.config.js、LICENSE-LEVELS.md 等仓库内源码与配置文件，系统讲解 CodeCombat 的项目定位、仓库结构、本地开发环境搭建、双产品构建架构、代码执行引擎 Aether、开源许可边界以及 Partner API 数据集成方式，帮助开发者快速上手这套"教学游戏 + 社区开源"的完整工程。

项目定位：一个同时是创业公司与社区项目的开源编程游戏

README 对 CodeCombat 的官方定义是："A multiplayer programming game for learning how to code"（一款用于学习编程的多人在线编程游戏）。它的独特之处在于双重身份：

• 游戏产品：玩家不是在抽象编辑器里做练习题，而是在真实游戏场景中编写代码驱动角色行动，游戏内积木块（Blockly）与代码模式（Ace 编辑器）并存，适合从零基础到进阶的各类学习者；
• 开源社区项目：代码完全开源，任何人都可以 fork、本地运行、参与开发。项目方在 README 中号召开发者加入"教会全世界编程"的使命，称贡献者的工作将展示给数以百万计的玩家（此为 README 中的项目方表述）。

仓库中还保留了完整的本地化体系（app/locale 下 60 余种语言的*.js文件）、课程内容（app/views/courses、app/templates/courses）、AI 相关模块（app/views/ai）以及另一条产品线 Ozaria（ozaria 目录），是一个工程规模相当可观的真实生产级项目。

仓库顶层结构与技术栈速览

从仓库根目录可以快速建立对工程的整体认知：

从 package.json 的依赖清单可以推断，前端技术栈以Backbone + Vue 2（2.7.10）+ CoffeeScript为主体：backbone ~1.1.1、vue 2.7.10、coffee-script 1.9.3，同时大量使用 webpack 5 处理.coffee、.pug、.sass、.vue等混合资源；游戏渲染采用 Phaser（phaser ^3.90.0），代码编辑采用 Ace（ace-builds）与 Blockly（blockly 10.3.0）双编辑器。服务端为 Express，并声明了明确的运行环境要求：

"engines": { "node": "22.22.1", "npm": "10.9.4" }

入口文件 index.js 在启动时会先检查 Node 主版本号：低于 v14 直接报错退出，低于 v14 打印升级警告；随后注册coffee-script加载器，根据COCO_PRODUCT环境变量选择产品后缀（coco或ozar），最终调用 server.js 中的startServer()创建 Express 应用并监听端口。

本地开发环境搭建与常用脚本

README 将完整的开发环境搭建教程指向项目维护的Archmage（开发者）wiki，仓库侧则以 package.json 的scripts字段和 Makefile 提供了可直接执行的任务入口。以下命令均以仓库根目录为工作目录执行。

环境准备

• Node.js（版本要求见上文engines，建议 22.x）；
• npm 10.9.4 或以上；
• 依赖安装：npm install会触发postinstall中的patch-package应用仓库内 patches 目录的补丁（如 Blockly 相关补丁）；此外项目还依赖 Bower 组件（bower install，由npm run build与npm run pre-build编排）。

常用 npm 脚本

Makefile 快捷目标

Makefile 将上述任务收敛为记忆成本更低的入口，执行make help可列出全部目标：

• make dev/make dev-ozaria：webpack watch 构建；
• make proxy/make proxy-ozaria：本地代理开发服务器（CodeCombat 端口 3000，Ozaria 端口 3001）；
• make build：完整生产构建（bower + aether + webpack）；
• make copy-i18n/make check-i18n/make generate-rot13：i18n 结构同步、超长翻译检查、ROT13 调试语言生成；
• make generate-levels：测试关卡生成算法（可传ARGS="--dry --debug"）；
• make build-aether：构建 Aether 引擎。

服务端配置要点

server_config.js 是服务端所有可调参数的集中地，开发时常用环境变量包括：

• COCO_PRODUCT：产品选择，codecombat或ozaria，决定productName与productMainDomain；
• COCO_PORT（或COCO_NODE_PORT、PORT）：监听端口，默认3000，单测模式下自动 +1；
• COCO_MAIN_HOSTNAME/COCO_UNSAFE_CONTENT_HOSTNAME：主站与不安全 web-dev iframe 内容的主机名，默认localhost:3000；
• COCO_COOKIE_SECRET：Cookie 签名密钥，默认'chips ahoy'（仅开发环境）；
• COCO_CHINA_INFRASTRUCTURE：中国区基础设施开关（与config.chinaDomain配合）；
• COCO_FORCE_COMPRESSION：开启服务端 gzip 压缩（生产环境由 CloudFlare 负责压缩，因此该开关仅用于开发环境测量响应体积）；
• COCO_SECRETS_JSON_BUNDLE：以 JSON 批量注入环境变量，用于密钥分发。

从 server.js 源码可见，服务启动流程为：createAndConfigureApp()创建 Express 实例 → 若开启压缩则挂载compression()→ 调用 server_setup.js 的setExpressConfigurationOptions与setupMiddleware配置中间件 →http.createServer(app).listen(app.get('port'))。

双产品构建架构：CodeCombat 与 Ozaria 共用一套工程

这是本仓库最具特色的工程实践之一：同一个代码仓库同时构建 CodeCombat 与 Ozaria 两个产品。机制核心是COCO_PRODUCT环境变量：

• development/utils.js 将产品映射为后缀：codecombat → coco、ozaria → ozar，并据此推导输出目录public_coco/public_ozar；
• index.js 与 webpack.base.config.js 均注册require.extensions['.coco.coffee']/'.ozar.coffee'之类的扩展名映射，使得foo.coco.bar、foo.ozar.bar形式的文件能被正确加载；
• webpack 配置中的ProductResolverPlugin在解析阶段把.import.sass等资源按产品后缀重写，实现一套源码按产品差异化编译；
• 入口 app/app.js 与 app/vendor.js 在 webpackentry中被声明，输出到javascripts/[name].js；world入口则聚合 app/lib/world 下的全部文件，用于 Worker 线程执行游戏世界逻辑；
• webpack.config.js 会根据环境自动选择子配置：COCO_TRAVIS_TEST→ karma 配置、BRUNCH_ENV=production→ 生产配置、COCO_ANALYZER_BUNDLE→ 包体积分析配置、DEV_CONTAINER→ 容器开发配置，否则默认开发配置。

前端还通过DefinePlugin注入COCO_PRODUCT与SHA_TAG（来自GIT_SHA或'dev'），CompileStaticTemplatesPlugin（compile-static-templates.js）负责把静态 Pug 模板预编译，Sass 编译时注入$is-codecombat变量以区分产品的样式变量。

核心执行引擎：Aether

游戏"代码即玩法"的核心在于一个名为Aether的代码执行引擎（app/lib/aether/aether.coffee）。它负责把玩家提交的代码在安全沙箱中解析、校验并执行：

• 基于 Esprima 解析器对 JavaScript 代码做静态分析，Aether 类通过optionsValidator（app/lib/aether/validators/options.coffee）校验构造参数，参数非法会直接抛出错误；
• 支持多语言：app/lib/aether/languages/下包含 9 个语言插件，结合 setup-aether.js 中从esper.js拷贝的lua、python、coffeescript（含-modern变体）语言插件，以及 Java/C++ 插件，实现跨语言代码的沙箱执行；
• 构建方式独立：setup-aether.js以独立的 webpack 配置把aether与html两个入口打包到bower_components/aether/build/，再将语言插件拷贝到public_*/javascripts/app/vendor/aether-*.js，由浏览器与 Service Worker 在运行时动态加载；
• 测试覆盖：仓库 spec/aether 下含javascript_spec.js、python_spec.js、java_spec.js、lua_spec.js、cs_spec.js、es6_spec.js、problem_spec.js等，覆盖多语言解析、报错、执行流与代码问题检测等维度。

开源许可与关卡授权边界

README 明确了项目的开源属性与边界，这在自托管时至关重要：

• 代码：采用 MIT 协议；
• 美术与音乐素材：采用 Creative Commons 4.0 BY（署名）协议；
• 关卡（Levels）：不开放源码。仓库内的 LICENSE-LEVELS.md 是一份中英双语的正式声明：CodeCombat Inc. 保留关卡的全部权利，关卡不公开、不允许在其它服务器上使用；若想运营公开的 CodeCombat 服务器，必须自己创建关卡，同时还应更换品牌、地址、团队与法律页面等配置，并对 CC-BY 素材署名。

因此，自托管 / 二次开发时的合规要点是：网站代码可以基于 MIT 协议自由修改分发，美术音效需按 CC-BY 署名，但千万不要打包或转载 codecombat.com 的关卡内容。

参与贡献：六种角色与 CLA

CONTRIBUTING.md 将贡献者分为六种角色，分别对应不同的协作方式：

• Archmage（法师）：代码贡献者，负责修 Bug、加功能；
• Artisan（工匠）：关卡搭建者，使用编辑器制作游戏关卡；
• Adventurer（冒险者）：关卡试玩测试者，反馈玩法体验；
• Scribe（书记官）：文章/文档编辑者；
• Diplomat（外交官）：翻译者，参与 app/locale 的多语言本地化；
• Ambassador（大使）：社区支持与推广。

提交 Pull Request 前，所有贡献者都必须签署贡献者许可协议（CLA）（README 与 CONTRIBUTING.md 均有强调）。该协议仅授予项目方非独占的使用许可，并确认贡献者有权提交其代码，用于保护双方权益。

社区沟通渠道在 README 中有明确说明：包括 Reddit 上的 CodeCombat 社区、项目的 issue tracker（问题追踪）以及官方开发者聊天室（Slack），团队欢迎从新手到专家的各类开发者参与。

Partner API 与用户数据集成

README 提供了两类数据接入方式，适合教育机构、集成方与个人开发者：

1. Partner API：面向有正式合作需求的机构，提供SSO 单点登录、用户管理、学习进度数据等能力的完整 API（需要向项目方申请 client credentials 客户端凭据），并配套官方 SDK。

2. 极简公开端点：最简单的数据集成方式是直接请求用户进度接口，例如访问形如https://codecombat.com/db/user/{用户名或ID}的端点，即可获得指定用户的进度统计 JSON 数据。README 提到外部工具 Beeminder 正是利用该接口，帮助用户把"学习编程"绑定为可跟踪的目标（如每日坚持打卡）。

这类"公开只读进度接口 + 需要凭据的 Partner API"的分层设计，让社区小工具可以低成本接入，同时为深度集成的机构保留完整的账户与数据管理能力。

小结

从 README.md 出发可以清晰看到 CodeCombat 的三条主线：游戏化编程学习产品（多人在线、真实代码驱动）、社区开源工程（MIT + CC-BY、双产品单仓库、Aether 沙箱执行引擎、覆盖 60 余种语言的本地化）以及开放数据接口（Partner API 与公开用户进度端点）。无论是想体验"用代码玩游戏"的玩家、希望本地搭建或二次开发的工程师，还是计划接入学习数据的集成方，都能在这套开源工程中找到明确的切入点——动手前请务必确认 LICENSE-LEVELS.md 关于关卡内容的授权边界。

• 游戏开发
• 教育
• 前端
• 后端