用 HuaweiCloud DevKit 沙箱 + DevBridge 隧道，10 分钟上线一个单文件 2048（附 3 个踩坑

前言

最近用 HuaweiCloud DevKit 在云沙箱里部署了一个自己写的 2048 小游戏：整个游戏就是一个 index.html（CSS 和 JS 全部内联，约 100 行），支持方向键/WASD、手机滑动和鼠标拖拽，最高分存在 localStorage。部署全程在 AI 编程助手（OpenCode）里通过 DevKit 的 MCP 工具完成，不用自己买服务器、不用配域名。下面把完整流程和踩过的坑整理出来，供想快速上线静态页面的同学参考。

一、环境准备

1. Node.js 22

DevKit 要求 Node ≥ 22，先确认版本：

node -v   # v22.x

国内网络可以切到华为云 npm 镜像：

npm config set registry https://mirrors.huaweicloud.com/repository/npm/

如果镜像同步滞后、装不到最新版，可以临时加 --registry=https://registry.npmjs.org。

2. 安装 KooCLI（hcloud）

npx --yes huaweicloud-devkit install-hcloud

3. 初始化凭证

npx --yes huaweicloud-devkit auth init

按提示输入 AK/SK，它会把凭证同步给 KooCLI、OBS 和沙箱 API。不要把 AK/SK 手写进 Agent 配置或 shell 环境变量，既不安全也容易和 DevKit 的配置不一致。

4. 安装到编程助手并自检

npx --yes huaweicloud-devkit install --target opencode
npx --yes huaweicloud-devkit doctor --target opencode

install 之后要重启一次会话，MCP 工具才会被加载。doctor 全绿再往下走，能省掉很多莫名其妙的问题。

二、部署三步走

第 1 步：上传文件 —— sandbox_upload_file

让助手调用 huaweicloud_sandbox_upload_file，把 index.html 上传到沙箱的 /workspace/game2048/。这个工具是分块 base64 上传并做 md5 校验，适合 1MB 以内的小文件，单文件游戏正合适。

第 2 步：起 Web 服务 —— sandbox_deploy_nginx

调用 huaweicloud_sandbox_deploy_nginx，根目录指向 /workspace/game2048，端口 3000。它会写 nginx 配置、修正目录权限并 reload。注意两点：

• 沙箱里没有 systemd，nginx 用 nginx -t 检查、nginx -s reload 重载；
• 端口被占用时工具会自动顺延，以返回结果里的实际端口为准。

第 3 步：公网访问 —— sandbox_expose_tunnel

调用 huaweicloud_sandbox_expose_tunnel，传入上一步的实际端口，拿到 https://<id>-<端口>.devbridge-s2.hwtunnel.com 形式的地址。工具会清理旧隧道、做一次健康检查，expiry_hours 可设 1–720（默认 72），并自动加入保活守护（每 5 分钟健康检查、断了自动重连）。打开链接，2048 就能在手机上玩了。

三、踩坑记录

坑 1：活动提交脚本报 PROJECT_ID_MISSING

用活动提交技能上报“沙箱部署”这一步时，服务端返回 PROJECT_ID_MISSING。看了脚本发现，它只在中级（ECS）里程碑才带 X-HW-PROJECT-ID / X-HW-REGION 请求头，而服务端对沙箱这一步也要求这个头。把判断改成始终携带这两个头后提交成功。遇到同样报错的同学可以先检查请求头，项目 ID 在控制台“我的凭证”里能查到，注意不要把它贴到公开的地方。

坑 2：deploy_nginx 报失败，其实服务已经起来了

有一次 deploy_nginx 返回失败/校验不通过，但实际上 nginx 已经在正常提供服务。别急着反复重部署，先在沙箱里确认：

nginx -t
curl -I http://127.0.0.1:3000

能返回 200 就说明服务正常，可以直接去开隧道。新版本 DevKit 已经加了写入校验，建议先 npx --yes huaweicloud-devkit update 升级。

坑 3：沙箱空闲停机后，隧道链接失效

过了一段时间再打开链接，页面显示 404 “tunnel not found”。这不是页面内容丢了，而是沙箱空闲被停掉，隧道的 host 进程跟着没了。解决办法：重新连接沙箱 → 重新执行 deploy_nginx → 重新 expose_tunnel。要注意重开后隧道地址会变，之前分享出去的链接（比如作品展示里填的地址）需要同步更新。需要长期展示的作品，建议把代码同时放到代码仓库，或者部署到 ECS/OBS 静态网站托管。

四、总结

对于单页面小应用，DevKit 沙箱 + DevBridge 隧道几乎是零成本上线方案：auth init 配好凭证，doctor 自检，然后“上传 → nginx → 隧道”三步就能拿到公网 HTTPS 地址，全程在编程助手里对话完成。三个经验：凭证只走 auth init；工具返回的端口和状态要用 curl 再核实一遍；沙箱是临时环境，隧道地址会随停机失效，长期展示要另做托管。希望对大家有帮助。