如果你逛过一些国外程序员的小站可能遇到过这种体验文章读到底页面底部突然出现一个像素风格的小地牢可以用方向键控制一个小人在走廊里移动甚至还能找到一扇通往下一层的地道。这种藏在博客“下面”的互动彩蛋在国外开发者圈子里被叫做dungeon under this blog——听起来像一句玩笑但它背后是一系列非常扎实的前端基础知识坐标系、渲染循环、碰撞检测、事件绑定以及“如何在复杂页面里安全地嵌入一段互动程序”。这篇文章想讲清楚的核心问题是怎么用最少的代码在一个技术博客的底部做一个能跑、能玩、还能展示编码功底的迷你地牢彩蛋。这个话题值得写的理由是它看似只是一个趣味项目实际上覆盖了前端游戏开发里最常用的那 20% 能力。你不需要 Three.js不需要游戏引擎只需要一个.html文件加一个.js文件就能跑出一个完整的小游戏。对于想接触游戏前端、想做个人网站彩蛋、或者想在团队内部做一次技术分享的开发者来说这是一个性价比极高的练手项目。全文会分为三大部分先看这类“页面彩蛋”有哪几种实现路径再拆解地牢游戏的核心概念最后给出一个完整的 Canvas 实现包括地图设计、玩家移动、碰撞检测、渲染循环以及嵌入博客时的注意事项和常见坑。读完以后你可以直接把这个思路复制到自己的站点里改成你自己的地图和玩法。1. 这篇博客下面为什么要藏一个地牢先回答一个最直接的问题为什么有人愿意花时间在博客页面里藏一个游戏从访客体验的角度看技术博客的阅读是一个单向输出过程读者滚动、阅读、滚动很少与页面产生交互。这时候如果页面底部出现一个可玩的彩蛋行为模式就变了——读者从“被动接收信息”切换成“主动探索页面”停留时间变长对站点的记忆点也更深刻。很多开发者会把这种彩蛋当成自己的个人名片用一个小游戏来传递风格和趣味。从技术学习的角度看这种项目非常适合作“最小可行游戏”的练习。它不涉及服务端、不涉及复杂的资源加载甚至不需要构建工具。一个 Canvas 标签、一张用二维数组表示的地图、一个方向键监听就能把游戏循环跑起来。而如果要升级成 3D 版本只需要把渲染层从 Canvas 2D 换成 Three.js游戏逻辑依然可以复用。从工程角度看这个需求其实很有挑战性彩蛋不能阻塞页面加载、不能把主文章挤乱、在移动端还不能把屏幕占满。它看起来是“炫技”实际上考察的是你对页面生命周期、事件机制和性能边界是否敏感。所以我的判断是地牢彩蛋真正的价值不是“玩”而是用极低的成本把前端游戏开发里的核心概念完整地走了一遍。如果你刚入门前端或者已经写了几年业务代码但对 Canvas 和游戏循环不太熟这个项目非常适合作为第一次“技术冒险”。2. 地牢游戏的三种实现路径与选型对比做一个“藏在博客下面的地牢”技术方案大致可以分为三类CSS 3D、Canvas 2D、WebGL / Three.js。2.1 纯 CSS 3D 方案纯 CSS 方案指的是利用transform-style: preserve-3d、rotateX()、translateZ()等属性构造一个 3D 空间再通过点击按钮或键盘事件改变视角。它最大的优点是轻量不依赖任何引擎也不要求 Canvas 环境缺点是游戏逻辑天然不好写碰撞检测、角色移动、地图数据管理都绕不开 JavaScript纯 CSS 只适合做“可旋转的静态场景”不太适合做真正的“可玩地牢”。2.2 Canvas 2D 方案Canvas 2D 是目前做 2D 小游戏最通用的方案。它通过 JavaScript 在画布上逐帧绘图地牢的墙壁、地板、玩家、出口都由代码绘制。它的特点是上手门槛低代码可控性强地图可以用二维数组直接描述非常适合做“网格移动”的复古地牢。由于不需要加载外部图片所有画面都是fillRect()、arc()这些 API 画出来的最终文件体积可能还不到 5KB。2.3 Three.js / WebGL 方案如果你想要真正能自由旋转视角的 3D 地牢就需要引入 Three.js。此时地牢不再是二维数组里的方格而是由立方体网格BoxGeometry构成的房间墙壁有厚度、地面有材质相机可以沿着走廊移动。代价是依赖体积变大需要处理加载、渲染循环、纹理和灯光。对于追求“视觉震撼”的彩蛋来说值得但对于大多数博客场景来说体积和复杂度可能超出需求。三种方案的选择建议其实很简单目标推荐方案理由最轻量、纯趣味纯 CSS 3D代码量少适合展示“空间感”可玩性 低依赖Canvas 2D地图、碰撞、移动都容易实现视觉冲击力Three.js真正的 3D 场景支持自由视角这篇文章的完整示例采用 Canvas 2D因为它在“代码量”和“可玩性”之间最平衡。3. 地牢游戏的核心概念从地图到渲染循环在写代码之前先把几个关键概念讲清楚不然直接看代码容易卡壳。3.1 网格地图地牢的本质是一张网格地图。在代码里网格地图通常用一个二维数组表示数组的每一行对应地图的一行数组元素的值代表这一格的内容。最常见的约定是0表示空地1表示墙壁2表示出口或传送点。二维数组的好处是直观并且天然支持“按坐标查找”MAP[y][x]可以直接拿到第y行、第x列的地图元素。这里要注意坐标顺序绝大多数情况下我们习惯先写行y再写列x但在实际排错时很容易写反。3.2 玩家的位置与移动在网格地牢里玩家一般不需要做像素级移动而是按“格子”移动按一次方向键走一格。这种设计大大简化了碰撞检测因为目标位置要么是 0空地、要么是 1墙壁只需要在移动前判断目标格子是不是墙即可。玩家位置一般用{ x, y }对象保存x 表示列索引y 表示行索引。移动时计算目标位置nx x dx、ny y dy然后做三步检查是否超出地图边界、是否撞墙、是否踩到出口。3.3 渲染循环传统的前端页面是一次性绘制而游戏需要持续刷新画面。最简单的做法是每次玩家按下方向键后重新绘制整张地图和玩家位置。因为地牢地图很小比如15 x 11全量重绘的开销完全可以忽略。更进阶的写法是用requestAnimationFrame()建立持续渲染循环。这个 API 告诉浏览器在下一帧刷新前执行一次回调函数。对于需要动画效果的地牢——比如楼梯动画、光圈扩散、角色走路摆动——就需要使用它。3.4 事件绑定与默认行为拦截玩家通过方向键控制角色需要监听keydown事件。这里有一个容易忽略的坑按下方向键时浏览器会默认滚动页面。如果彩蛋嵌在博客底部玩家按上方向键整个页面会跟着滚上去体验非常差。所以需要调用event.preventDefault()拦截默认行为。4. 环境准备与项目结构这个项目对运行环境的要求非常低。只要满足以下条件就完全够了任意现代浏览器推荐 Chrome 或 Edge一个文本编辑器VS Code 或记事本都可以可选一个本地静态服务器用于模拟“从站点加载资源”的真实场景不需要安装任何 npm 包不需要配置构建工具也不需要联网加载 CDN 资源。整个项目只有两个文件dungeon-demo.html和dungeon.js。如果你是在本地直接用浏览器打开dungeon-demo.html可以用file://协议运行因为代码里没有请求外部资源。但如果你想在博客里嵌入它建议在项目根目录启动一个静态服务器推荐方式python3 -m http.server 8080然后访问http://localhost:8080/dungeon-demo.html。之所以推荐这种方式是因为后续如果扩展成多个文件、或者引入图片和音频资源file://协议会因为浏览器安全策略而拦截一些请求。项目结构保持简单blog-dungeon/ ├── dungeon-demo.html └── dungeon.js生产环境中你还可以把这两个文件放到一个单独的目录例如demo/dungeon/然后通过路径引用。5. 完整代码实现用 Canvas 做可玩的地牢下面从零开始写一个可运行的地牢彩蛋。这个版本包含地图、墙壁、出口、玩家移动、碰撞检测和通关提示并且保持所有绘图逻辑都基于 Canvas 2D API。5.1 创建 HTML 页面与画布先创建dungeon-demo.html负责页面结构、样式和 Canvas 初始化。!-- 文件路径blog-dungeon/dungeon-demo.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title博客下面的地牢 - 迷你示例/title style body { margin: 0; background: #1e1e2e; display: flex; justify-content: center; align-items: center; min-height: 100vh; font-family: monospace; } canvas { border: 2px solid #333; background: #0d0d12; max-width: 100%; height: auto; } .tip { color: #aaa; text-align: center; margin-top: 8px; font-size: 13px; } /style /head body div canvas iddungeon width480 height360/canvas div classtip使用方向键移动找到黄色的出口/div /div script srcdungeon.js/script /body /html这个文件做了三件事定义了满屏居中展示的页面布局创建了一个宽 480、高 360 的画布并通过script src引入后续要写的游戏逻辑。CSS 里的max-width: 100%是为了在移动设备上不让画布超出屏幕。5.2 地图、玩家移动与碰撞检测核心代码在dungeon.js中实现。我把地图、绘制逻辑、移动逻辑和事件绑定拆成几个清晰的部分。// 文件路径blog-dungeon/dungeon.js const canvas document.getElementById(dungeon); const ctx canvas.getContext(2d); const TILE 32; // 地图0 空地1 墙壁2 出口 const MAP [ [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1], [1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 1], [1, 0, 1, 2, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1], [1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1], [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1], [1, 0, 1, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1, 0, 1], [1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1], [1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1], [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1] ]; const ROWS MAP.length; const COLS MAP[0].length; let player { x: 1, y: 1 }; let message ; function isWall(x, y) { return MAP[y][x] 1; } function draw() { ctx.clearRect(0, 0, canvas.width, canvas.height); for (let row 0; row ROWS; row) { for (let col 0; col COLS; col) { const cell MAP[row][col]; const px col * TILE; const py row * TILE; if (cell 1) { ctx.fillStyle #4a4a5a; ctx.fillRect(px, py, TILE, TILE); } else { ctx.fillStyle #101018; ctx.fillRect(px, py, TILE, TILE); ctx.strokeStyle #222230; ctx.strokeRect(px 0.5, py 0.5, TILE - 1, TILE - 1); } if (cell 2) { ctx.fillStyle #ffd166; ctx.fillRect(px 10, py 10, 12, 12); } } } ctx.fillStyle #06d6a0; ctx.beginPath(); ctx.arc( player.x * TILE TILE / 2, player.y * TILE TILE / 2, 10, 0, Math.PI * 2 ); ctx.fill(); if (message) { ctx.fillStyle #ffffff; ctx.font 16px monospace; ctx.fillText(message, 20, canvas.height - 16); } } function move(dx, dy) { const nx player.x dx; const ny player.y dy; if (nx 0 || ny 0 || nx COLS || ny ROWS) { return; } if (isWall(nx, ny)) { return; } player.x nx; player.y ny; if (MAP[ny][nx] 2) { message 恭喜你找到了出口; } } document.addEventListener(keydown, (e) { switch (e.key) { case ArrowUp: move(0, -1); break; case ArrowDown: move(0, 1); break; case ArrowLeft: move(-1, 0); break; case ArrowRight: move(1, 0); break; default: return; } e.preventDefault(); draw(); }); draw();这段代码的逻辑并不复杂但有几个地方值得重点解释。第一步定义TILE 32表示每一格占 32 像素。画布宽 480 像素可以画 15 列高 360 像素可以画 11 行所以地图设计成了11 x 15的规模正好填满画布。第二步初始化玩家位置为{ x: 1, y: 1 }对应地图第 1 行第 1 列。这个位置被设计成空地玩家出生点周围没有墙。第三步move()函数是碰撞检测的核心。它先计算目标坐标然后做两个判断是否越界、是否撞墙。只有两个条件都不满足时才更新玩家位置。如果目标位置是出口就设置通关提示。第四步draw()函数是每帧的渲染工作。它遍历所有格子墙壁用深灰色填充地板用更深的颜色加网格线绘制出口画成黄色方块玩家画成一个绿色圆形。这里的绘制顺序很关键先画地板、再画墙壁、最后画玩家保证玩家总是显示在最上层。最后一步监听键盘事件。因为这里用的是e.key而不是e.keyCode所以代码的可读性更好也避免了一些浏览器兼容问题。每次移动后调用draw()重绘画布而不是立刻清除再画整体上是一个非常典型的最小渲染循环。5.3 把地牢嵌入博客的三种方式本地运行通过后下一步是把它放进博客。这里要分场景看。如果你的博客是自己控制的独立站点最稳妥的方式是把整个地牢做成一个页面然后用iframe嵌入到文章底部!-- 嵌入到博客文章底部iframe 方式 -- iframe src/demo/dungeon/index.html width480 height400 loadinglazy title迷你地牢彩蛋 /iframe用iframe的优点是隔离性好页面的 CSS 不会和博客样式互相污染JavaScript 的全局变量也不会冲突。loadinglazy可以延迟加载不影响文章首屏速度。如果博客平台支持自定义 HTML 片段也可以直接把 Canvas 和script src标签嵌入页面!-- 直接嵌入到支持自定义 HTML 的博客中 -- div classblog-dungeon-wrapper canvas iddungeon width480 height360/canvas /div script src/assets/js/dungeon.js/script不过要注意这种方式要求脚本和外链资源可由你控制。如果你的博客平台只允许 Markdown 文本、不允许自定义脚本那就只能用iframe引用一个你部署好的独立页面或者放弃脚本功能改为只展示一张静态效果图并附上源码链接。还有一种思路是把地牢做成控制台彩蛋。在浏览器开发者工具里打开别的技术博客时偶尔能看到站长在 console 里打印字符画和招聘信息。同样的思路也可以用在项目首页判断用户是否按下了键盘组合键再触发地牢小游戏。这种方式不占用页面空间更像一个隐藏成就// 在页面主脚本里监听隐藏入口 let secretKey ; document.addEventListener(keydown, (e) { secretKey e.key; secretKey secretKey.slice(-4); if (secretKey dung) { openDungeonModal(); // 打开地牢弹窗 secretKey ; } });6. 运行验证与效果检查代码写完以后按照下面的步骤验证效果。第一步在项目目录下启动本地静态服务器python3 -m http.server 8080第二步在浏览器中访问http://localhost:8080/dungeon-demo.html预期效果是页面居中显示一个深色背景的地牢地图地图四周是一圈墙壁内部有若干分隔墙黄色出口位于地图第三行附近绿色圆形玩家从左上角出发。第三步用方向键验证移动。按上、下、左、右玩家应该每次移动一格继续按方向键页面不应该跟着滚动移动到墙壁位置时玩家会被挡住。第四步把玩家移动到黄色出口所在格子画面底部应该出现提示文字“恭喜你找到了出口”。如果某个环节没通过不要着急看控制台。先按照下面的顺序检查打开浏览器控制台F12看是否有红色报错。最常见的问题是dungeon.js路径写错导致 Canvas 元素拿不到。检查地图数组的维度是否和画布尺寸匹配。按当前TILE 32、画布480 x 360计算地图必须是 15 列x11 行。检查是否有其他脚本抢先占用了keydown事件。如果页面上还有其他全局键盘监听并调用了stopPropagation()地牢可能收不到键盘事件。7. 常见问题与排查思路问题现象可能原因排查方式解决方案玩家无法移动键盘事件未绑定到 document在keydown监听里打日志确认使用document.addEventListener而不是canvas.addEventListener按方向键时页面滚动没有调用preventDefault()滚动时观察 URL 变化在keydown回调中调用e.preventDefault()地图显示不完整或溢出地图行列数与画布尺寸/瓦片大小不匹配计算ROWS * TILE是否超过画布高度调整地图尺寸或TILE的值画布空白dungeon.js加载失败在控制台查看资源加载状态检查script标签的路径嵌入博客后被 CSS 拉伸变形博客全局样式对canvas设置了宽度或高度用浏览器开发者工具查看画布元素的计算样式给画布设置max-width: 100%并保持宽高比iframe 加载后白屏资源路径使用绝对路径错误直接访问 iframe 的 src 地址确认部署后的资源路径建议使用相对路径这里最容易踩的坑是 CSS 干扰。博客平台通常有一套全局样式会强制让所有canvas、img标签变成display: block并设置宽度。如果你的画布因此被拉伸墙面就会变成变形玩家圆形变成椭圆。解决方法是给画布包一层容器并单独设置样式。另外在 iframe 方式下如果博客设置了X-Frame-Options响应头只允许同源页面嵌入那你会看到 iframe 区域为空白。遇到这种情况需要确认目标页面是否允许被其他页面嵌入。8. 最佳实践与工程建议如果把地牢从“本地 demo”升级成“博客正式彩蛋”下面这几条建议会很有用。性能方面地牢地图通常很小全量重绘没有压力。但如果未来准备扩展成更大的地图或者加入更多动画角色建议把渲染逻辑改成“按需绘制”只重绘发生变化的格子。同时要避免在draw()里频繁调用font设置或创建新的渐变对象这些操作在持续渲染循环中是性能杀手。移动端适配键盘事件在手机上不可用所以至少需要补充两个能力一是画布自适应屏幕宽度二是提供触摸或点击按钮。最简单的做法是在画布下方加四个按钮分别对应四个方向点击时调用move()函数。按钮的样式要足够小不影响文章阅读。可访问性游戏彩蛋不应该影响主要内容的可读性。如果使用 iframe建议加上title属性方便读屏软件识别。如果地牢对某些用户不可见或不可操作也要保证它不会遮挡正文或造成布局跳动。代码组织不要把所有代码写进一个巨大的dungeon.js。推荐把地图数据单独放到map.js把绘图逻辑和移动逻辑分层。如果使用模块化可以考虑用 ES Module// 文件路径dungeon/modules/map.js export const MAP [ // 地图数据省略 ];引入路径管理当博客路径发生变化时iframes 里的src很容易失效。建议先定义统一的资源根路径再拼接出最终 URL。如果你使用 GitHub Pages 或静态站点生成器尽量采用相对路径避免在子目录下找不到资源。回退方案如果用户禁用了 JavaScript或者浏览器不支持 Canvas彩蛋区域不应该出现大块空白。可以在canvas标签内写一段提示文字作为降级内容canvas iddungeon width480 height360 你的浏览器不支持 Canvas或脚本被禁用无法显示地牢彩蛋。 /canvas因为当浏览器支持 Canvas 时canvas内的文本不会显示不支持时才显示这段提示。这是一个成本很低的降级策略。团队协作如果你是在团队项目里推广这个玩法建议把地牢代码放到独立目录并配一份 README说明地图数组规则、如何新增关卡、如何调整玩家速度。否则两周以后很可能没人知道自己当年在哪个文件里画了个地图。9. 总结与后续可以玩的方向这个“地牢”项目的价值不在于它本身有多炫酷而在于它用非常小的体量覆盖了前端交互开发里最常用的核心能力用二维数组建模、用事件系统接收输入、用 Canvas 渲染画面、用坐标和条件判断实现碰撞检测。跑通这个项目之后你可以基于它做很多变体。第一个方向是扩展地图和玩法。把地图改成多楼层走到出口后进入下一层每层地图不同难度递增。也可以加入钥匙和门捡到钥匙才能打开某个方向的特殊墙壁。第二个方向是升级渲染方式。把 Canvas 2D 的绘制逻辑替换成 Three.js用立方体构建墙壁用第一人称视角控制移动。你会发现网格和碰撞检测的思维完全复用只是渲染层的 API 变了。第三个方向是把它接入头像系统。让玩家可以选择不同颜色、输入名字生成一个属于自己的角色然后在地牢里看到一个简单的排行榜。这样它就从“彩蛋”变成了一个小型社区功能。如果你本来就有个人博客建议直接动手不要只看不练。把这个彩蛋放到博客底部观察访客停留时间和行为数据得到的反馈会比任何教学文章都有说服力。希望这篇教程能帮你在自己的博客下面挖出一个属于自己的小地牢。