herryyun/ark-stronghold-protocol
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
ark-stronghold-protocol/docs/WINDOWS.md
T

9.9 KiB
Raw Permalink Blame History

Windows 便携包（零安装方案）

本文说明怎么打一份「目标机器什么都不用装」的 Windows 便携包，包里放了什么、没放什么，以及发出去之前要确认的授权。 相关代码：scripts/make-windows-bundle.mjs（打包）、scripts/launch.mjs（准备 + 起服务器 + 打开浏览器）。

1. 这份包解决什么

便携包只做一件事：让这台 Windows 电脑当服务器——包内自带 Node、素材与生产依赖，目标机器什么都不用装， 双击 启动游戏.bat 就在本机开服并自动打开浏览器，控制台会打印可以发给朋友的局域网地址 （自己玩、或和同宿舍/同办公室的朋友玩）。

连别人的服务器不需要这个包：直接用浏览器打开对方的网址就行，和你在浏览器里输网址是同一件事， 本机不用跑服务、不用下素材。包里因此没有「连接服务器」这个入口。

2. 打一份便携包

先准备素材（public/assets、public/fonts、public/vendor 都不进版本库）：

node tools/setup.mjs

然后在仓库里（任意平台，只要有 Node 22+ 且能上网下载官方 Node 归档）执行：

node scripts/make-windows-bundle.mjs                    # 产物默认在 <仓库上一级>/Stronghold-Protocol-Windows
node scripts/make-windows-bundle.mjs --out D:\Game\Stronghold-Protocol-Windows --force
node scripts/make-windows-bundle.mjs --no-node          # 目标机器已装 Node 22+ 时不必带便携 Node
node scripts/make-windows-bundle.mjs --node-version v22.23.3 --sha256 <64 位十六进制>   # 换 Node 版本

--out 请给一个专用目录（像上面那样指到某个父目录下的子目录）。加 --force 时只会删掉两种情况： 目录是空的，或者里面就是上一次打的便携包（包根有 README-开箱即用.md 和 app\）。 其余情况一律拒绝并提示 —— 免得手滑把 --out 指到仓库、桌面或者其它有东西的目录上，--force 就把它们删了。 指向仓库本身或仓库的上级目录时更是在第一步就被挡下来。

产出的始终是 Windows 包（内含 win-x64 的 node.exe），但它可以在 macOS / Linux 上打： 官方归档解压出来的布局固定是 <zip 名>/node.exe，与打包机器是什么系统无关。

产物内容：

node\node.exe            官方 Windows x64 便携版 Node（版本与 sha256 钉在仓库里，只取 node.exe）
node\LICENSE-node.txt    Node 自己的许可证（MIT，与 node.exe 出自同一个官方归档）
app\                     游戏本体：代码 + 生产依赖 + public（全部素材）+ data，完全离线
启动游戏.bat             app\scripts\launch.mjs --no-setup
README-开箱即用.md       给玩家看的说明（含非官方 / 严禁盈利 / 素材版权声明）
LICENSE / NOTICE.md / THIRD-PARTY-NOTICES.md

把整个文件夹拷到目标电脑 —— 什么都不用安装，双击 启动游戏.bat 即可（等于 app\scripts\launch.mjs --no-setup： 素材已经在包里，跳过联网准备，直接起服务器并打开浏览器）。 卸载＝删除文件夹（不写注册表、不放系统目录）。素材约 330 MB 是硬成本，包因此比较大。

3. 包里放了什么、没放什么

app\ 的文件清单来自 git ls-files，不是手写的跳过表。因此被 .gitignore 挡在版本库外的本机文件 （.env、.venv*、.claude/、scripts/service.env.cmd …）天然进不了包 —— 它们里面可能有密钥或本机路径，旧实现用一张窄表整树复制，漏一项就是把它打进别人下载的压缩包。

在此之上额外放入三份不进版本库、但游戏必需的资源，以及用 npm ci --omit=dev 重新装好的生产依赖：

  • public/assets、public/fonts、public/vendor（由 tools/setup.mjs 下载 / 生成）；
  • node_modules 只含生产依赖 —— puppeteer-core 这类 devDependency 是开发测试用的，打进发行包只会白涨体积；
  • data/local-assets.json（本机提取过 3D 棋盘贴图时才有）：贴图本体在 public/assets/local（约 68 MB，会随 public/assets 进包），但游戏是靠这份 JSON 才知道有哪些贴图可用 —— 只带贴图不带清单，玩家拿到的是 68 MB 用不上的文件。清单不存在时会提示先跑 node tools/setup.mjs --local。
  • test/ 一律不进包（省体积）。

整树复制时会跳过符号链接与点开头的条目：打包机器的 .DS_Store 既不属于项目，也不该出现在别人下载的包里。

Node 版本与 sha256 钉死在 scripts/make-windows-bundle.mjs 的 NODE_PIN 里（不用 latest-v22.x）： 那样今天打包和上个月打包内容不同，出了问题也无法复现。换版本必须显式给 --node-version（要写成 vX.Y.Z 这样的 具体版本）+ --sha256。

官方 zip 的下载缓存放在仓库的 .cache/（不进版本库），而 node.exe 每次都从校验过的 zip 重新解压： 解压目标是新建的临时目录、用完即删。缓存的是 zip，不是解压结果 —— 解压中断留下的残缺 node.exe 与校验过的 zip 没有任何对应关系，复用就等于把坏文件发出去；系统临时目录在 Linux 上还是共享的。 解压器按平台兜底：tar（Windows 10+ 与 macOS 自带的 bsdtar 都认得 zip）→ unzip（GNU tar 解不了 zip， Linux 上是这一档）→ Windows 自带的 Expand-Archive。

关于 --out 与 --force：--out 指向仓库本身或它的上级目录时直接拒绝；即使指到别处，--force 也只会在 「目录是空的」或「里面就是上一次打的便携包（包根有 README-开箱即用.md 和 app\）」时才删除， 其它情况一律拒绝并不动那个目录 —— 路径比较挡不住大小写、符号链接、8.3 短名这些花样，所以规则是反着写的： 只有能确认「这就是上次的产物」才动手。

4. 授权（发出去之前请确认你同意）

便携包把整个游戏原样带给别人，所以包根会带上本项目的声明文件，包内 README-开箱即用.md 也完整重复了一遍：

Important

  • 本项目是玩家自制的非官方同人作品，与上海鹰角网络科技有限公司（Hypergryph）、Yostar 及其关联方没有任何关系，未获其授权或认可。
  • 《明日方舟》及「卫戍协议」相关的名称、角色、美术、音乐、音效、文本与数据等素材，版权归原权利人所有。这些素材不适用本项目的 GPL-3.0 许可证；GPL 只覆盖本项目自己编写的代码。
  • 仅供学习交流与个人非商业使用。严禁任何形式的盈利，包括但不限于：售卖本项目或整合包、付费下载或付费分发、收费服务器或收费代开、广告 / 打赏 / 会员等变现方式，以及其他任何商业用途。
  • 本包为了方便玩家附带了游戏的美术与音频素材，下载即视为同意本声明。请勿将素材用于本项目以外的用途或单独再分发。完整条款见 NOTICE.md。
  • 权利人如认为本项目侵犯其权益，请通过 Issue 联系，我们会立即删除相关内容。
  • 本项目按「现状」提供，不提供任何担保，使用风险自负。

内置 Node.js（MIT）与其它第三方组件的许可见 THIRD-PARTY-NOTICES.md 与 node\LICENSE-node.txt（node.exe 自己的许可证，从同一个官方归档里取出来一起发）。

5. 常见问题

症状 处理
双击 .bat 一闪而过 在命令行里跑 启动游戏.bat 看报错，或手动运行 node\node.exe app\scripts\launch.mjs --no-setup（.bat 会在非 0 退出时暂停）。--no-setup 别省：省掉它会去联网准备素材，而且 PATH 上不一定有 node
提示找不到 node 便携包应含 node\node.exe；没有就用 --no-node 的包，并自行安装 Node 22/24 LTS
端口被占用 关掉占用 3000 的程序（node tools/doctor.mjs 会指出是谁），或在启动命令后加 --port 3001
浏览器没自动打开 手动访问 http://127.0.0.1:<端口>；--no-open / SP_NO_BROWSER=1 会禁用自动打开
朋友连不上 防火墙专用网络未放行、或不在同一网段；用 node tools/doctor.mjs 诊断（源仓库里见 DEPLOY.md 的防火墙一节）
进游戏时弹出「下载文件信息」 那是 IDM / 迅雷这类下载管理器在嗅探音频地址，不是游戏在下载。新版本已经改走不带扩展名的 /media/… 路由（见 PR #28），应该不会再弹；如果还弹，把弹出的地址贴到 Issue，或在下载器里加例外（如 http://127.0.0.1:3000/*）、玩游戏时先退出它
首次进游戏很慢 每位玩家要下载几十 MB 素材（本机开服时是本机读盘），之后走浏览器缓存
在 Linux 上打包报解压失败 GNU tar 不认 zip：装一个 unzip（或在文档允许的范围内改用 macOS / Windows 打包）

6. 安全与体积说明

  • 便携包里的 node.exe 来自 nodejs.org 官方发行版，按仓库里钉死的 sha256 校验后才复制，未做任何修改； 同时取出同一个归档里的 LICENSE 作为 node\LICENSE-node.txt 一起发出去。
  • app\ 里只有版本库跟踪的文件 + 生产依赖 + 素材 + 3D 棋盘清单，被 .gitignore 排除的本机文件 （.env、.claude/、scripts/service.env.cmd 等）不会进包。
  • 游戏不写注册表、不装服务；启动游戏.bat 内容只有几行（切到 UTF-8 代码页 → 找 node\node.exe → 跑 app\scripts\launch.mjs --no-setup）。
  • 想做成随开机启动的 Windows 服务，用仓库自带的 scripts/install-service-windows.ps1（面向整合包/源码部署，见 DEPLOY.md）。
Reference in new issue View Git Blame Copy Permalink