企业官网建设流程全解析

1. 项目缘起与整体架构设计

1.1 为什么要用 TypeScript 重写一款经典 RPG

第一次冒出"用 TypeScript 从零重写一款经典 RPG"这个念头，其实源于一次很偶然的折腾。当时我在整理旧硬盘，翻出了一堆二十多年前的老游戏存档，心血来潮想重温一下，结果发现要在现代浏览器里跑起来，得装模拟器、配环境、调兼容性，折腾半天还不一定能稳定运行。那一刻我就在想，与其费劲去适配老引擎，不如干脆用现代前端技术栈把这类游戏的核心玩法重新实现一遍——既能跑在任意浏览器里，又能顺便把游戏逻辑和内容生产工具一起做了。

这个项目最终落地的形态是两部分：一个能完整通关的浏览器版 RPG，以及一个给游戏做内容（剧情、地图、对话、战斗配置）的可视化编辑器。技术选型上，我几乎没怎么犹豫就选了 TypeScript。原因很直接：RPG 这类游戏的状态极其复杂——角色属性、背包、任务标记、地图坐标、战斗回合、剧情分支，任何一处类型写错，都会在运行时炸出一堆难以定位的 bug。TypeScript 的静态类型系统能在编译期就拦下大部分低级错误，尤其是当游戏逻辑膨胀到几千行之后，类型带来的安全感是纯 JavaScript 给不了的。

从架构上看，我把整个项目拆成了三层：引擎层负责渲染循环、输入处理、资源加载、场景切换；逻辑层负责角色、战斗、任务、对话等纯数据驱动的规则；内容层则是编辑器产出的 JSON 配置。三层之间通过明确的接口通信，引擎层不关心具体剧情，逻辑层不关心怎么渲染，内容层更是完全数据化。这种分层的好处是，编辑器可以独立于游戏运行，产出的配置文件直接丢给游戏读取即可，两边互不干扰。

1.2 浏览器版 RPG 的核心需求拆解

很多人一听"浏览器里做 RPG"，第一反应是"性能扛得住吗"。实测下来，只要不是做 3D 大作，2D 像素风的 RPG 在浏览器里跑得相当流畅。真正难的不是性能，而是状态管理和内容组织。

我把核心需求拆成了这么几块。第一是地图与移动：角色要能在格子地图上行走，有碰撞检测，有场景切换（比如从村庄走到野外）。第二是对话与剧情：NPC 要能触发对话，对话要支持分支选项，选项要能影响后续剧情走向。第三是战斗系统：回合制战斗，包含攻击、技能、道具、逃跑等指令，要有伤害计算和状态效果。第四是存档与读档：玩家进度要能保存到本地，刷新页面不丢失。第五是背包与装备：物品的获取、使用、装备属性加成。

这五块需求里，最容易被低估的是对话与剧情。因为剧情分支一旦多起来，用硬编码的 if-else 写会迅速变成一团乱麻。我的做法是把所有剧情抽象成节点图：每个对话是一个节点，节点里包含文本、说话人、以及若干选项，每个选项指向下一个节点 ID。这样剧情就变成了纯数据，编辑器负责可视化地连这些节点，游戏运行时只需要一个"节点解释器"去遍历即可。这个设计决策后面会反复提到，因为它是整个项目能同时支撑"游戏"和"编辑器"的关键。

1.3 可视化编辑器的定位与价值

单独做一个游戏，其实不需要编辑器——手写 JSON 也能凑合。但一旦剧情量上来，手写配置就是灾难。我踩过的坑是：早期剧情只有十几段对话时，手写 JSON 还能忍；等到主线加支线超过两百段对话，改一个 NPC 的名字要在几十个文件里搜索替换，改错一个逗号整个游戏就白屏。

所以编辑器的定位很明确：让内容生产脱离代码。它要能可视化地编辑地图（拖拽格子、刷地形）、编辑对话树（连线、加节点）、编辑战斗配置（敌人属性、掉落表）、编辑物品和技能。编辑器本身也是 TypeScript 写的，和游戏共享同一套类型定义——这意味着编辑器里配置的数据结构，和游戏运行时读取的结构完全一致，从根本上杜绝了"编辑器导出的格式游戏读不懂"这类问题。

这里有个关键设计：类型定义单独抽成一个共享包。游戏和编辑器都依赖这个包，任何一方改了数据结构，另一方编译时就会报错，强制两边保持同步。这个做法在多人协作时尤其重要，我一个人做的时候也受益匪浅，因为隔几周回来改代码，类型定义就是最好的文档。

2. 核心技术点深度解析

2.1 游戏主循环与渲染方案选型

浏览器里做游戏渲染，绕不开两个选择：Canvas 2D还是DOM。我最终选了 Canvas 2D，理由是这样的：DOM 渲染虽然写起来直观（每个精灵就是一个 div），但一旦同屏元素超过几百个，浏览器的重排重绘开销就会明显上升，而且做像素级对齐、图层叠加、动画插值都很别扭。Canvas 2D 则是"一块画布画所有"，控制粒度细，性能稳定，配合requestAnimationFrame能轻松跑满 60 帧。

主循环的结构我用了经典的固定时间步长 + 插值渲染。简单说，逻辑更新固定按每秒 60 次（即每帧 16.67ms）推进，渲染则根据实际帧率做插值，这样即使某台设备掉帧，游戏逻辑速度也不会忽快忽慢。核心代码大概长这样：

const FIXED_STEP = 1000 / 60; let accumulator = 0; let lastTime = performance.now(); function loop(now: number) { const delta = now - lastTime; lastTime = now; accumulator += delta; while (accumulator >= FIXED_STEP) { update(FIXED_STEP); accumulator -= FIXED_STEP; } render(accumulator / FIXED_STEP); requestAnimationFrame(loop); }

这段代码看起来简单，但里面有个坑：如果页面被切到后台，requestAnimationFrame会暂停，回来时delta可能高达几万毫秒，while循环会一次性跑几千次更新，直接卡死。所以我在update里加了最大补偿帧数限制，超过就丢弃多余时间。这个细节在官方文档里基本不会提，但实际项目里不加就是定时炸弹。

2.2 地图系统：格子、图层与碰撞

地图我用的是**瓦片地图（Tile Map）**方案。一张地图由若干图层叠加而成：底层是地面（草地、泥土、水面），中层是装饰（花草、石头），上层是遮挡物（树冠、屋顶），最上面是碰撞层。每个图层就是一个二维数组，数组里存的是瓦片 ID。

碰撞检测我用了最朴素也最可靠的格子级 AABB。角色移动时，先算出目标格子坐标，然后查碰撞层，如果是障碍就阻止移动。这里有个手感问题：如果严格按格子走，角色会像跳棋一样一格一格跳，很生硬。我的做法是让角色在格子之间做平滑插值移动，但碰撞判定仍然按目标格子算。这样视觉上是丝滑的，逻辑上又是精确的。

地图数据我定义成这样的结构：

interface GameMap { id: string; width: number; height: number; tileSize: number; layers: { ground: number[][]; decor: number[][]; overlay: number[][]; collision: boolean[][]; }; portals: Portal[]; // 场景切换点 npcs: NpcPlacement[]; }

portals是场景切换的关键。每个传送点记录了自己的格子坐标、目标地图 ID、目标坐标。角色踩上去就触发切换。这个设计让"从村庄走到野外"变成了纯数据配置，编辑器里点两下就能连好，不需要写任何代码。

2.3 对话树与剧情分支的数据结构

前面提到剧情用节点图，具体的数据结构是这样的：

interface DialogueNode { id: string; speaker: string; text: string; choices?: DialogueChoice[]; next?: string; // 无选项时的下一节点 condition?: Condition; // 触发条件 effect?: Effect[]; // 触发效果，如给物品、改标记 } interface DialogueChoice { text: string; next: string; condition?: Condition; }

condition和effect是让剧情"活"起来的关键。比如某个选项只有在玩家拥有某件物品时才出现，这就是condition；选了某个选项后玩家获得一把剑，这就是effect。我把 condition 和 effect 都做成了可序列化的表达式对象，而不是函数——因为函数没法存进 JSON，编辑器也没法可视化编辑。表达式对象长这样：

type Condition = | { type: 'hasItem'; itemId: string } | { type: 'flag'; key: string; value: boolean } | { type: 'level'; min: number }; type Effect = | { type: 'giveItem'; itemId: string; count: number } | { type: 'setFlag'; key: string; value: boolean } | { type: 'startBattle'; enemyId: string };

运行时用一个evaluateCondition函数去解释这些对象。这个设计的好处是，编辑器可以给每种 condition 类型做一个表单界面，策划填表单就行，完全不用碰代码。这也是"游戏"和"编辑器"能共享同一套数据的关键。

2.4 回合制战斗的状态机实现

战斗系统我用的是状态机。一场战斗会经历这些状态：selectCommand（等待玩家选指令）、executeAction（执行动作动画）、checkResult（判定胜负）、enemyTurn（敌人行动）、end（战斗结束）。每个状态负责自己的逻辑，状态之间通过明确的事件切换。

伤害计算我参考了经典 RPG 的公式，简化后是这样的：

基础伤害 = 攻击力 * 2 - 防御力 最终伤害 = 基础伤害 * 随机系数(0.9 ~ 1.1) 若暴击，最终伤害 *= 1.5

这个公式的好处是直观、好调。攻击力翻倍，伤害大致翻倍；防御力堆到接近攻击力两倍时，伤害趋近于零但不会为负。随机系数让战斗有波动但不至于失控。暴击率我设成 10%，暴击倍率 1.5 倍，这个数值是反复试出来的——太高了战斗没策略性，太低了玩家没爽感。

战斗状态机的难点在于动画和逻辑的同步。比如"攻击"这个动作，逻辑上瞬间就结算完了，但视觉上要播放挥剑、受击、掉血数字三个动画。我的做法是逻辑先算出结果，把结果塞进一个"动画队列"，状态机进入executeAction后逐帧消费这个队列，队列空了才切到下一个状态。这样逻辑和表现就解耦了，改动画不影响战斗数值。

3. 可视化编辑器的实现路径

3.1 编辑器整体界面布局与技术栈

编辑器我用的技术栈是React + TypeScript + Canvas。为什么用 React？因为编辑器的界面本质上是"一堆表单 + 一块画布"，表单部分用 React 管理状态非常舒服，画布部分则用 Canvas 保证性能。两者结合，各取所长。

界面布局分三栏：左侧是资源面板（地图列表、对话树列表、物品列表、敌人列表），中间是主编辑区（根据选中的资源类型切换成地图编辑器或对话树编辑器），右侧是属性面板（编辑当前选中对象的详细属性）。顶部是工具栏（新建、保存、导出、导入）。

这个布局是参考了主流游戏引擎编辑器的思路，但做了大幅简化。因为我的目标用户是"会写点剧情但不太懂技术"的人，界面越简单越好。所以我没有做复杂的停靠面板、多标签页，就是固定的三栏，切换资源类型时中间区域整体替换。

3.2 地图编辑器的拖拽与刷子实现

地图编辑器最核心的交互是刷子：选一个瓦片，在地图上点或拖，就把那个格子刷成选中的瓦片。实现上，我把鼠标事件转成格子坐标，然后修改对应图层的二维数组，最后触发重绘。

function handleCanvasClick(e: React.MouseEvent) { const rect = canvasRef.current!.getBoundingClientRect(); const x = Math.floor((e.clientX - rect.left) / tileSize); const y = Math.floor((e.clientY - rect.top) / tileSize); if (x < 0 || y < 0 || x >= map.width || y >= map.height) return; map.layers[currentLayer][y][x] = selectedTileId; redraw(); }

拖拽刷子稍微复杂点，要处理鼠标按下、移动、抬起三个事件，并且移动时要做插值——因为鼠标移动是离散的，快速拖动时两个事件之间的格子会被跳过。我的做法是记录上一个格子坐标，每次移动时用 Bresenham 算法把两个格子之间的路径都刷上。这个细节不做的话，快速画线会断断续续，体验很差。

碰撞层我用一个单独的开关切换：打开"碰撞编辑"模式后，点击格子就是切换该格子的碰撞状态（true/false），用红色半透明覆盖显示。这样策划能直观看到哪里能走哪里不能走。

3.3 对话树编辑器的节点连线方案

对话树编辑器是我花时间最多的部分。核心难点是节点的自动布局和连线的可视化。节点布局我用了简单的分层算法：从根节点开始 BFS，每层的节点横向排列，层与层之间纵向间隔固定距离。这个算法不完美，复杂剧情会有交叉线，但胜在实现简单、结果稳定。

连线我用的是贝塞尔曲线，从父节点底部连到子节点顶部。每条线中间加一个可点击的箭头，点击可以删除这条连线。节点本身是一个可拖拽的卡片，显示说话人、文本前几个字、以及选项数量。双击节点打开右侧属性面板，可以编辑完整文本和选项。

这里有个体验优化：节点搜索。剧情多了以后，找某个特定节点很痛苦。我加了一个搜索框，输入关键词能高亮匹配的节点并自动滚动过去。这个小功能看似不起眼，但实际用起来能省大量时间。

3.4 数据校验与导出机制

编辑器最怕的是"导出后游戏读不了"。我的防线是导出前全量校验。校验内容包括：所有next和choice.next指向的节点 ID 必须存在；所有引用的物品、敌人、地图 ID 必须存在；地图的传送点目标坐标必须在目标地图范围内；对话树必须有且仅有一个根节点。

校验不通过时，编辑器会列出所有错误，点击错误能跳转到对应位置。只有全部通过才允许导出。这个机制帮我拦下了无数次手误，尤其是改剧情时删了某个节点却忘了改指向它的连线。

导出的格式就是纯 JSON，按资源类型分文件：maps.json、dialogues.json、items.json、enemies.json。游戏启动时并行加载这几个文件，加载完就能跑。因为编辑器和游戏共享类型定义，导出的 JSON 结构天然就是游戏期望的结构，不需要任何转换层。

4. 实操过程与关键环节记录

4.1 从零搭建项目骨架的完整步骤

第一步是初始化项目。我用的是 Vite 作为构建工具，因为它启动快、配置少。命令很简单：

npm create vite@latest rpg-project -- --template react-ts cd rpg-project npm install

然后我把项目拆成三个包：packages/shared（共享类型）、packages/game（游戏本体）、packages/editor（编辑器）。用 npm workspaces 管理：

{ "workspaces": ["packages/*"] }

shared包里只放类型定义和纯函数（比如伤害计算、条件求值），不依赖任何运行时环境，这样游戏和编辑器都能用。game和editor各自独立构建，互不干扰。

第二步是搭游戏主循环。我先写了一个最小的 Canvas 渲染循环，能画一个方块并让它响应方向键移动。这一步跑通后，再逐步往里加地图、角色、碰撞。千万不要一上来就写完整架构，那样很容易卡在某个抽象层里出不来。我的经验是：先让一个方块动起来，再让它走在地图上，再让它撞墙停下，一步一步来。

4.2 资源加载与图片切图的处理细节

RPG 的素材通常是一张大图，里面排列着各种瓦片和角色帧。加载后需要切图：把大图按固定尺寸切成小图，存进一个缓存。我用的是离屏 Canvas 做切图：

function sliceTileset(image: HTMLImageElement, tileSize: number) { const cols = Math.floor(image.width / tileSize); const rows = Math.floor(image.height / tileSize); const tiles: HTMLCanvasElement[] = []; for (let y = 0; y < rows; y++) { for (let x = 0; x < cols; x++) { const c = document.createElement('canvas'); c.width = tileSize; c.height = tileSize; c.getContext('2d')!.drawImage( image, x * tileSize, y * tileSize, tileSize, tileSize, 0, 0, tileSize, tileSize ); tiles.push(c); } } return tiles; }

切好的瓦片存进数组，渲染时直接drawImage(tiles[id], ...)。这里有个性能细节：关闭图像平滑。像素风游戏如果开了平滑，放大后会糊成一片。所以要在绘制前设置ctx.imageSmoothingEnabled = false。这个设置是全局的，设一次就行，但很容易忘，忘了画面就毁了。

资源加载我用Promise.all并行加载所有图片，加载完再启动游戏。加载过程中显示一个进度条。这里要注意加载失败的处理：某张图 404 了不能让整个游戏卡死，要记录错误并继续，用占位图代替。我在开发期就遇到过素材路径写错导致游戏白屏，排查了半天才发现是加载 Promise 一直 pending。

4.3 存档系统的序列化与版本兼容

存档我用的是localStorage，把游戏状态序列化成 JSON 存进去。状态包括：当前地图 ID、角色坐标、角色属性、背包、已触发的剧情标记、任务进度。序列化本身简单，难的是版本兼容。

游戏更新后，数据结构可能变了，老存档读进来就会缺字段。我的做法是在存档里加一个version字段，读取时先检查版本，如果低于当前版本，就跑一个迁移函数把老结构转成新结构。比如 v1 的背包是数组，v2 改成了对象，迁移函数就负责转换。这个机制在游戏还在迭代时特别重要，不然每次更新玩家存档就废了。

function migrateSave(save: any): SaveData { if (save.version < 2) { save.inventory = Object.fromEntries( save.inventory.map((item: any) => [item.id, item.count]) ); save.version = 2; } return save as SaveData; }

存档我做了三个槽位，每个槽位独立存储。自动存档在每次场景切换时触发，手动存档由玩家在菜单里操作。自动存档和手动存档分开，避免自动存档覆盖了玩家想保留的进度。

4.4 编辑器与游戏的数据联调流程

联调流程是这样的：在编辑器里改完内容，点导出，编辑器会生成 JSON 文件并触发下载。我把这些 JSON 放到游戏的public/data目录下，游戏启动时从那里加载。开发期为了省事，我写了一个脚本，把编辑器导出的文件直接复制到游戏目录，省去手动下载再拖拽的步骤。

联调时最容易出问题的是ID 对不上。比如编辑器里给某个敌人配了掉落物品sword_01，但物品表里没有这个 ID，游戏运行时就会报错。所以我在游戏加载数据后加了一个启动自检：遍历所有引用关系，检查是否有悬空引用，有就在控制台报警告。这个自检在开发期帮我省了大量排查时间。

另一个联调细节是热重载。改完 JSON 后不想每次都重启游戏，我加了一个开发模式下的快捷键，按 R 重新加载数据文件并重置当前场景。这样改一句对话，按一下 R 就能看到效果，迭代速度飞快。

5. 常见问题与排查技巧实录

5.1 性能问题：掉帧与内存泄漏排查

掉帧最常见的原因是每帧都在创建新对象。比如渲染时每次都new Path2D()或者拼接字符串，垃圾回收器频繁触发，帧率就抖。我的做法是把能复用的对象都缓存起来，渲染循环里只做读写不做创建。

内存泄漏我遇到过一次，排查了很久。原因是事件监听器没解绑：每次切换场景都addEventListener，但离开场景时没removeEventListener，监听器越积越多。后来我封装了一个Scene基类，在destroy方法里统一清理监听器和定时器，所有场景继承它，问题就解决了。

排查工具上，Chrome DevTools 的 Performance 面板能看帧率曲线，Memory 面板能看内存增长。我的经验是：如果内存曲线呈锯齿状（涨了又降），那是正常的 GC；如果一直往上爬不降，那就是泄漏，得去查哪里只增不减。

5.2 类型报错：TypeScript 严格模式下的常见坑

开了strict: true之后，最常见的报错是Object is possibly 'undefined'。比如map.layers.ground[y][x]，TS 不知道y和x是否越界，就报可能 undefined。我的处理是加边界检查，或者用非空断言!——但非空断言要慎用，用多了等于关掉了类型保护。

另一个坑是联合类型的收窄。比如Condition是个联合类型，访问condition.itemId时 TS 会报错，因为不是所有分支都有这个字段。正确做法是先用type字段判断，收窄后再访问：

if (condition.type === 'hasItem') { return inventory[condition.itemId] > 0; }

这个模式在写 condition 求值函数时反复出现，写熟了就很自然。

5.3 编辑器卡顿：大量节点时的渲染优化

对话树节点超过一百个后，编辑器开始卡。原因是每次拖动节点都触发全量重绘。我的优化是分层渲染：把静态的连线画在一个离屏 Canvas 上，只有节点变化时才重画连线；节点本身画在主 Canvas 上，拖动时只重画节点层。这样拖动就流畅了。

另一个优化是视口裁剪：只渲染当前可见区域内的节点。节点多了以后，屏幕外的节点根本不需要画。加上这个优化后，即使五百个节点也不卡。

5.4 常见问题速查表

这张表是我踩坑踩出来的，基本覆盖了开发期 90% 的问题。建议把它贴在显示器旁边，遇到问题先对照一遍，能省不少时间。

6. 项目扩展与个人经验分享

6.1 后续可以怎么扩展这套框架

这套框架的扩展性其实挺强的。最直接的扩展是加更多玩法系统，比如合成系统、宠物系统、成就系统。因为数据都是配置化的，加系统主要是加类型定义和对应的编辑器面板，游戏逻辑改动不大。

另一个方向是多人协作。目前编辑器是纯前端的，数据存在本地。如果要多人一起做内容，可以加一个后端，把 JSON 存到数据库，编辑器通过 API 读写。这样策划、美术、程序可以同时工作，各改各的部分。不过多人协作会引入冲突问题，需要加锁或者版本合并机制，这是另一个话题了。

还可以做移动端适配。目前游戏是键盘操作的，加一套虚拟摇杆和触摸按钮就能上手机。Canvas 渲染在移动端性能也够用，主要工作是 UI 布局的响应式调整。

6.2 我在这个项目里踩过的几个大坑

第一个大坑是过早优化。项目初期我花了两周设计了一套"完美"的 ECS（实体组件系统）架构，结果发现 RPG 这种游戏根本用不上那么重的架构，反而让简单逻辑变复杂了。后来我推倒重来，用最朴素的面向对象写法，代码量少了一半，可读性还更好。教训是：架构要跟着需求长，不要提前长。

第二个大坑是忽视编辑器体验。早期编辑器做得很糙，改个对话要填一堆表单，我自己都不爱用。后来我花时间优化了交互——加搜索、加拖拽、加实时预览——内容生产效率立刻上来了。教训是：编辑器是给自己用的工具，工具不好用，内容就做不出来。

第三个大坑是没有版本控制数据。有次改剧情改乱了，想回退却发现没有历史记录，只能凭记忆重写。后来我给编辑器加了操作历史，支持撤销重做，还能导出快照。这个功能救了我好几次。

6.3 给想复现这个项目的朋友的建议

如果你也想做类似的项目，我的建议是先做最小可玩版本。不要一上来就想着做编辑器、做完整剧情，先让一个角色能在地图上走动、能触发一句对话、能打一场战斗。这个最小闭环跑通后，你就有信心往下做了。

技术选型上，TypeScript 强烈建议开 strict。虽然初期会多写一些类型代码，但后期省下的调试时间远超投入。渲染用 Canvas 2D 就够了，除非你要做 3D，否则没必要上 WebGL。

最后，内容比技术更重要。一个技术平平但剧情有趣的 RPG，比一个技术炫酷但内容空洞的 RPG 更让人愿意玩下去。所以别在技术上钻牛角尖，把省下的时间花在打磨剧情和数值上，回报更高。

我在实际做这个项目的过程中最大的体会是：游戏开发和普通前端开发是两种思维。普通前端是"响应事件、更新界面"，游戏是"维护一个持续演进的状态，每帧渲染这个状态"。想清楚这个区别，很多设计决策就顺了。另外，编辑器那部分虽然看起来是"附加功能"，但它其实是整个项目能持续做下去的关键——没有好的内容生产工具，再好的引擎也只是个空壳。