前言
最近尝试运行一个有趣的开源项目 OpenSC2K——一个用 JavaScript 编写的《模拟城市 2000》开源重制版。这个项目使用 Phaser 3 游戏引擎和 WebGL 渲染。本文记录了从克隆项目到成功运行的完整过程，以及遇到的各种问题和解决方案。
项目背景
- 项目名称：OpenSC2K
- 技术栈：JavaScript, Phaser 3, WebGL, Webpack 4
- 原作者：Nicholas Ochoa (原 GitHub 用户名：rage8885)
- 特点：需要原版 SimCity 2000 的游戏资源文件
遇到的问题与解决方案
问题 1：依赖包 404 错误
错误信息：
error Error: https://codeload.github.com/rage8885/dat.gui/tar.gz/3ea8447b2ced3f08eb25ec2a89e0e22baec91b40: Request failed "404 Not Found" error Error: https://codeload.github.com/rage8885/bmp-js/tar.gz/...: Request failed "404 Not Found"
原因分析：
- 项目的原始
package.json中引用了作者自己 fork 的依赖库 - 原作者的 GitHub 用户名从
rage8885改为了nicholas-ochoa - 但是那些 fork 的依赖库（
rage8885/bmp-js,rage8885/dat.gui）并没有随用户名一起迁移 - 这些旧的 fork 仓库已经不存在，导致依赖包无法从 GitHub 下载
原始的 package.json 依赖部分：
{
"dependencies": {
"@vingle/bmp-js": "rage8885/bmp-js",
"bmp-js": "rage8885/bmp-js",
"dat.gui": "rage8885/dat.gui",
"file-saver": "^2.0.0",
"jquery": "^3.4.0",
"jszip": "^3.1.5",
"phaser": "3.16.0-rc2"
}
}
解决方案：
用官方 npm 版本替代那些已失效的 GitHub 依赖。打开 package.json 文件，手动修改以下三个依赖：
修改后的依赖部分：
{
"dependencies": {
"@vingle/bmp-js": "^0.2.5",
"bmp-js": "^0.1.0",
"dat.gui": "^0.7.9",
"file-saver": "^2.0.0",
"jquery": "^3.4.0",
"jszip": "^3.1.5",
"phaser": "3.16.0-rc2"
}
}
同时更新 repository 相关字段（反映作者用户名变更）：
{
"homepage": "https://github.com/nicholas-ochoa/OpenSC2K",
"repository": {
"type": "git",
"url": "https://github.com/nicholas-ochoa/OpenSC2K.git"
}
}
完整步骤：
- 手动编辑
package.json：- 将上述三个依赖改为官方 npm 版本
- 更新
homepage和repository.url
重新安装依赖：
yarn install
清理 yarn 缓存：
yarn cache clean
清理旧的安装文件：
# Windows 命令行
del yarn.lock
rmdir /s /q node_modules
为什么这样做有效？
- 官方的
bmp-js、@vingle/bmp-js和dat.gui包在 npm 上是可用的 - 虽然可能与作者的 fork 版本略有不同，但核心功能是兼容的
- 使用官方版本避免了对已删除 GitHub 仓库的依赖
- 后续我们会修复因版本差异导致的代码兼容性问题（见问题 5）
问题 2：Webpack 配置文件路径错误
错误信息：
Error: Cannot find module 'D:\jiangcaidu\code\bs\OpenSC2K\.\webpack.config.js'
原因分析：
package.json中的 scripts 使用了单引号包裹路径- Windows 命令行处理单引号时产生了转义问题
解决方案：
修改 package.json 的 scripts 部分：
{
"scripts": {
"dev": "webpack-dev-server --progress --config webpack.config.js"
}
}
关键点：去掉路径两边的单引号，或者干脆省略 --config 参数（webpack 默认会查找 webpack.config.js）。
问题 3：Node.js 与 Webpack 4 兼容性问题
错误信息：
Error: error:0308010C:digital envelope routines::unsupported at new Hash (node:internal/crypto/hash:101:19) at Object.createHash (node:crypto:139:10)
原因分析：
- 我使用了 Node.js v20（较新版本）
- 项目使用 Webpack 4（较老版本）
- Node.js 17+ 移除了 Webpack 4 使用的旧版 OpenSSL 加密算法
解决方案：
方案 A：使用环境变量（推荐）
修改 package.json：
{
"scripts": {
"dev": "set NODE_OPTIONS=--openssl-legacy-provider && webpack-dev-server --progress --config webpack.config.js"
}
}
方案 B：降级 Node.js
# 如果安装了 nvm (Node Version Manager)
nvm install 16
nvm use 16
方案 C：升级到 Webpack 5（需要修改配置，较复杂，不推荐新手）
推荐：方案 A 最简单，无需修改 Node.js 版本。
问题 4：游戏资源文件缺失，导致黑屏
错误信息（浏览器控制台）：
Failed to load resource: the server responded with a status of 404 (Not Found) :3000/assets/import/PAL_MSTR.BMP:1 :3000/assets/import/LARGE.DAT:1
原因分析：
- OpenSC2K 需要原版 SimCity 2000 的游戏资源文件
- 由于版权原因，这些文件不包含在项目仓库中
- 必须合法获取原版游戏并提取资源
解决方案：
- 购买游戏（合法途径）：
- GOG.com - 约 $3-5 美元（推荐）
- Steam（如果有）
- 其他密钥商店（G2A, Kinguin 等）
游戏安装目录通常在：
C:\GOG Games\SimCity 2000 Special Edition\ 或 C:\Program Files (x86)\GOG Galaxy\Games\SimCity 2000 Special Edition\
提取游戏文件：
# 创建目录
mkdir assets
mkdir assets\import
# 从 SimCity 2000 安装目录复制以下文件到 assets\import\：
# - PAL_MSTR.BMP
# - LARGE.DAT
# - 以及其他 .BMP 和 .DAT 文件
注意：此错误通常是因为未仔细阅读
README.md文件。
问题 5：bmp-js 库兼容性问题
错误信息（浏览器控制台）：
Uncaught TypeError: First argument must be a string, Buffer, ArrayBuffer, Array, or array-like object. at new palette (palette.js:10:35) at LoaderPlugin.<anonymous> (world.js:26:22)
原因分析：
- 官方
bmp-js库的 API 与作者修改版略有不同 bmp.decode()方法对参数类型有严格要求
解决方案：
修改 src/import/palette.js 文件的 parse() 方法：
原代码（第 60-62 行）：
parse() {
// decode BMP file into an array of pixels (rgba)
let file = bmp.decode(this.buffer);
}
修改为：
parse() {
// decode BMP file into an array of pixels (rgba)
// Ensure buffer is in the correct format for bmp-js
let bufferData = this.buffer;
if (!Buffer.isBuffer(bufferData)) {
bufferData = Buffer.from(bufferData);
}
let file = bmp.decode(bufferData);
}
说明：这段代码确保传入 bmp.decode() 的参数是有效的 Buffer 对象。若仍存在问题，请检查是否缺少资源 .BMP 和 .DAT 文件。
完整的项目配置
最终的 package.json
{
"name": "OpenSC2K",
"description": "An Open Source remake of SimCity 2000",
"author": "Nicholas Ochoa",
"version": "0.6.0",
"homepage": "https://github.com/nicholas-ochoa/OpenSC2K",
"repository": {
"type": "git",
"url": "https://github.com/nicholas-ochoa/OpenSC2K.git"
},
"license": "GPL-3.0",
"main": "index.js",
"scripts": {
"dev": "set NODE_OPTIONS=--openssl-legacy-provider && webpack-dev-server --progress --config webpack.config.js"
},
"dependencies": {
"@vingle/bmp-js": "^0.2.5"
项目目录结构
OpenSC2K/
├── assets/
│ └── import/ # 需要手动创建并添加游戏资源
│ ├── PAL_MSTR.BMP
│ ├── LARGE.DAT
│ └── ... (其他资源文件)
├── src/
│ ├── import/
│ │ └── palette.js # 需要修改的文件
│ └── ...
├── package.json # 需要修改依赖
├── webpack.config.js
└── ...
运行步骤总结
1. 克隆项目
git clone https://github.com/nicholas-ochoa/OpenSC2K.git
cd OpenSC2K
2. 修改配置文件
- 修改
package.json（依赖和 scripts） - 修改
src/import/palette.js（bmp-js 兼容性）
3. 安装依赖
yarn install
# 如果遇到 browserslist 警告（可选）
yarn upgrade caniuse-lite browserslist
4. 添加游戏资源
- 从合法渠道购买 SimCity 2000
- 提取资源文件到
assets/import/目录
5. 启动开发服务器
yarn dev
6. 访问游戏
打开浏览器访问：http://localhost:3000/
总结
通过这次调试过程，我们成功让一个几年前的项目在现代环境中运行起来。这个过程涉及了依赖管理、版本兼容性、类型转换、版权问题等多个方面的知识。
OpenSC2K 是一个很有趣的项目，展示了如何用 Web 技术重制经典游戏。虽然遇到了一些问题，但通过系统的排查和解决，最终还是成功运行了。
相关链接：
