game-deploy

游戏部署

将你的浏览器游戏部署到公网，供所有人访问。here.now 是默认选项——即时静态托管，零配置。需要基于 git 部署时，也可以使用 GitHub Pages。

here.now 部署（默认）

前置条件

• 已安装 here-now 技能（npx skills add heredotnow/skill --skill here-now -g）
• 可选：$HERENOW_API_KEY 或 ~/.herenow/credentials，用于永久托管

快速部署

npm run build
~/.agents/skills/here-now/scripts/publish.sh dist/

脚本会输出一个可访问的网址，例如 https://<slug>.here.now/。

here.now 为什么是默认选项

• 零配置——无需设置 base 路径、无需 git 仓库，也无需 GitHub CLI
• 即时生效——网站立即上线（无需等待传播）
• 没有 base 路径问题——内容从子域名根目录提供（base: '/' 或使用默认值）
• 随处可用——只需要 curl、file 和 jq

Vite base 路径

here.now 从子域名根目录提供内容，因此使用默认 base 路径：

export default defineConfig({
  base: '/',
  // ... rest of config
});

重要：请在 24 小时内认领你的网站

如果没有 API 密钥，发布内容将以匿名方式发布，并在 24 小时后过期。发布脚本会返回一个认领网址——用户必须访问此网址并创建免费的 here.now 账户，才能永久保留网站。**认领令牌只会显示一次，无法找回。**如果用户未认领，网站就会消失。

**每次匿名发布后，你都必须告知用户 24 小时的期限以及认领网址。**这不是可选操作。

功能	匿名	已验证身份
过期时间	24 小时（之后将被删除！）	永久
最大文件大小	250 MB	5 GB
速率限制	5 次/小时/IP	60 次/小时/账户

如需设置 API 密钥以实现永久托管（完全跳过 24 小时期限）：

首先检查密钥是否已存在： test -f .env && grep -q '^HERENOW_API_KEY=.' .env && echo "found" 如果已找到，使用 set -a; . .env; set +a 导出该密钥，并跳过询问步骤。

否则：

1. 询问用户的邮箱地址
2. 发送魔法链接：curl -sS https://here.now/api/auth/login -H "content-type: application/json" -d '{"email": "[email protected]"}'
3. 用户点击链接，然后从控制面板复制 API 密钥
4. 用户粘贴密钥，格式如下：HERENOW_API_KEY=their-key-here（保存到 .env 并自动隐藏）
5. 还要将密钥保存到凭据文件：mkdir -p ~/.herenow && grep '^HERENOW_API_KEY=' .env | cut -d= -f2- > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials

更新部署

npm run build
~/.agents/skills/here-now/scripts/publish.sh dist/ --slug <slug>

每次发布后，slug 都会保存到 .herenow/state.json——脚本会在更新时自动加载它。

部署脚本

添加到 package.json：

{
  "scripts": {
    "deploy": "npm run build && ~/.agents/skills/here-now/scripts/publish.sh dist/"
  }
}

更新现有 slug：

{
  "scripts": {
    "deploy": "npm run build && ~/.agents/skills/here-now/scripts/publish.sh dist/ --slug <slug>"
  }
}

GitHub Pages 部署（替代方案）

需要基于 git 部署或已经设置好 GitHub 仓库时，可使用 GitHub Pages。

前置条件

• 已安装 GitHub CLI（gh）
• 已初始化 Git 仓库并推送到 GitHub

快速部署

npm run build && npx gh-pages -d dist

完整设置

1. 构建游戏：

npm run build

2. 如果部署到子目录，请确保 vite.config.js 中设置了正确的 base 路径：

export default defineConfig({
  base: '/<repo-name>/',
  // ... rest of config
});

3. 使用 GitHub CLI 部署：

gh repo create <game-name> --public --source=. --push
npm install -D gh-pages
npx gh-pages -d dist

4. 在仓库设置中启用 GitHub Pages（应该会自动检测到 gh-pages 分支）。

你的游戏将在此网址上线：https://<username>.github.io/<repo-name>/

自动部署

添加到 package.json：

{
  "scripts": {
    "deploy": "npm run build && npx gh-pages -d dist"
  }
}

Play.fun 注册

部署后，在 Play.fun 上注册你的游戏以实现变现。使用 /game-creator:playdotfun 技能查看集成详情。

注册时，部署网址将作为你的 gameUrl：

await client.games.register({
  name: 'Your Game Name',
  gameUrl: 'https://<slug>.here.now/',  // or GitHub Pages URL
  maxScorePerSession: 500,
  maxSessionsPerDay: 20,
  maxCumulativePointsPerDay: 5000
});

其他托管选项

• Vercel：npx vercel --prod（自动检测 Vite）
• Netlify：连接仓库，将构建命令设为 npm run build，将发布目录设为 dist
• Railway：使用 Railway 技能进行部署
• itch.io：将 dist/ 文件夹作为 HTML5 游戏上传

使用示例

默认（here.now）

/game-deploy

结果：构建 dist/ → 通过 here.now 发布 → 几秒内即可在 https://<slug>.here.now/ 运行游戏。添加 npm run deploy 脚本，方便日后通过一条命令完成部署。

GitHub Pages

/game-deploy github-pages

结果：使用正确的基础路径进行构建 → 推送到 gh-pages 分支 → 1-2 分钟后即可在 https://<user>.github.io/<game>/ 运行游戏。

故障排除

here.now 429 速率限制

原因： 短时间内部署次数过多。here.now 对匿名部署进行了速率限制。 解决方法： 等待几分钟后重试。若需要频繁部署，可考虑改用 GitHub Pages 或 Vercel。

匿名 here.now 网站已过期

原因： 匿名 here.now 部署是临时的，闲置一段时间后会过期。 解决方法： 使用 npx here.now 重新部署。若需要持久托管，请使用 GitHub Pages（gh-pages 分支）或 Vercel，它们不会过期。

部署后 GitHub Pages 出现 404

原因： Vite 的基础路径与 GitHub Pages 的 URL 结构（/<repo-name>/）不匹配。 解决方法： 在 vite.config.js 中设置 base: '/<repo-name>/'。确保在仓库的 Pages 设置中选择 gh-pages 分支作为源。等待 1-2 分钟，让 GitHub 的 CDN 完成传播。

部署后页面空白（资源路径）

原因： 资源路径使用了绝对 URL（/assets/...），无法在部署主机上正确解析。 解决方法： 使用相对路径（./assets/...），或配置 Vite 的 base 选项，使其与部署 URL 匹配。在本地运行 npm run build，并在部署前通过本地服务测试 dist/ 文件夹。

推送 gh-pages 被拒绝

原因： 远程 gh-pages 分支已分叉，或强制推送被分支保护规则阻止。 解决方法： 如果你拥有该仓库且没有分支保护规则，可使用 git push origin gh-pages --force。如果分支受保护，请先删除远程 gh-pages 分支：git push origin --delete gh-pages，然后重新部署。

部署前检查清单

• npm run build 成功完成，且没有错误
• 使用 npm run preview 测试生产构建
• 删除所有用于调试的 console.log 语句
• 确认构建中包含所有资源
• 如适用，检查移动设备上的显示和响应式行为
• 在 index.html 中设置合适的 <title> 和 meta 标签