vibehost-deploy

部署到 VibeHost

将构建好的静态网站或 Next.js 应用在几秒钟内上线到 VibeHost，并获取一个私有 URL。

何时适用此技能

用户提出类似以下需求时：

• “发布这个”“部署这个”“把这个上线”“托管这个”“发布这个”
• “给我一个这个构建的预览 URL”
• “把这个发到预发布环境 / 生成一个演示链接”

或者你刚刚生成了静态构建输出（dist/、out/、build/）或 Next.js 构建，此时自然的下一步就是托管它。

如果用户还没有 VibeHost 账号，请引导他们访问 https://vibehost.com/signup — 部署需要经过身份验证的会话。

设置

通过下载、检查并运行安装程序来安装 CLI — 不要直接将它通过管道传给 shell：

# macOS / Linux; installs one static binary, user-level only (no sudo)
curl -fsSL -o vibehost-install.sh https://vibehost.com/install.sh
cat vibehost-install.sh   # review it first: the script verifies the CLI binary's
                          # SHA256 against the release manifest before installing
sh vibehost-install.sh && rm vibehost-install.sh

vibehost login        # device-flow browser login; or VIBEHOST_TOKEN env var for headless/CI
vibehost whoami        # confirm session + which workspace is active

安装程序只会写入 ~/.vibehost/ 和 ~/.local/bin 中的一个 bin shim — 不会修改 shell 配置文件，也不需要 root 权限。它会发送匿名安装信标（平台、shell 版本、成功/失败）；设置 VIBEHOST_NO_TELEMETRY=1 即可选择退出。

身份验证可以通过以下任一方式完成：之前运行过 vibehost login（令牌位于 ~/.config/vibehost/config.json）、环境变量中的 VIBEHOST_TOKEN PAT（无头模式/CI），或 https://api.vibehost.com/mcp 上的 MCP OAuth 会话。大多数命令都支持以便于脚本处理的输出格式运行的 --json；解析输出时优先使用它。

VibeHost 可以托管什么

• 静态网站（默认运行时）— 根目录中包含 index.html 的任意目录（dist/、out/、build/ 或纯 HTML）。
• Next.js 应用（私有测试版） — 使用 --runtime nextjs 启用。支持 App Router、SSR、ISR、服务器操作和图像优化；仅预渲染的构建会通过静态快速路径自动提供服务（无需容器）。需要数据库的应用可以使用托管 Postgres（vibehost db、Neon serverless），而不是外部 DB。如果 app create --runtime nextjs 返回 NEXTJS_RUNTIME_GATED，表示此运行时当前无法供此用户/工作区使用（访问权限可能取决于平台、工作区和用户限制）— 请改用静态导出（output: 'export' + 部署 ./out），或向工作区所有者申请访问权限。

推荐方式：CLI

vibehost CLI 将应用创建、文件哈希计算、blob 上传和部署整合为一条命令，并显示进度。只要可以运行 shell 命令，就优先使用它。

vibehost app create my-app                  # once per app; name: lowercase, 2–40 chars, [a-z][a-z0-9-]*
vibehost deploy ./dist --app my-app --json  # every time

# Next.js app instead of a static build (private beta — see above; server build by default):
vibehost app create my-app --runtime nextjs --json
vibehost deploy . --app my-app --json       # sandboxed server build; no local next build required
# Or explicitly build on the user's machine:
vibehost deploy . --app my-app --build client --json

--json 输出格式为 { ok: true, data: { url, immutableUrl, ... } }。只有在部署运行正常后，命令才会以 0 退出，因此成功退出就意味着 URL 已上线。

提示：在项目中运行 vibehost link --app my-app 会写入 .vibehost/project.json，之后无需任何标志即可运行 vibehost deploy。

无法使用 shell 时：MCP 服务

如果无法运行 shell，但已连接到 https://api.vibehost.com/mcp 上的 MCP 服务，部署需要通过一系列工具调用完成。请阅读每个工具自身的 description，以获取权威的参数架构 — 下方列出了名称和顺序，但不要依据本文档硬编码参数格式。

1. list_apps — 查找工作区中已有的应用。
2. create_app — 仅当目标应用不存在时调用（{ name, workspaceId }）。
3. check_blobs_missing — 传入文件的 SHA-256 值，了解服务端还缺少哪些文件。
4. request_upload — 为缺少的 SHA 生成预签名 PUT URL，然后通过普通 HTTP 将原始字节 PUT 到每个 URL（Content-Type: application/octet-stream）。
5. deploy — { appId, channel?, manifest[] }。会立即返回 { deploymentId, status: "starting" } — 网站此时尚未上线。
6. get_deployment — 使用 deploymentId 轮询，直到 status 为 healthy（已上线）、failed（查看错误）或 superseded。

提供给用户的内容

务必展示结果中的两个 URL：

• 别名 URL（url）— 指向此频道的最新部署。分享给他人时使用此 URL。
• 不可变 URL（immutableUrl）— 固定指向此确切构建。用于错误报告、评审链接和存档演示。

常见问题

• 根目录下没有 index.html——静态部署需要此文件。对于客户端路由的 SPA（React Router、Vue Router、Remix SPA 模式），遇到路径未匹配时，边缘节点必须提供 index.html；请参阅 https://docs.vibehost.com/guides/static-sites。请不要添加 _redirects 文件——VibeHost 不会解析该文件（这是 Netlify/Pages 的约定）。
• Tarball 被拒绝——构建包过大或格式错误时，会触发 TARBALL_INVALID；error.details 会说明原因。请精简大型资源（视频、生产环境源映射文件、多余的 node_modules），或升级套餐。
• 工作区错误——作用域为工作区 A 的令牌若要部署到工作区 B 中的应用，会返回 TOKEN_WORKSPACE_MISMATCH。请明确提示此错误，不要悄悄改在其他工作区重试。
• 查询 ID，不要猜测——appId 和 workspaceId 来自 list_apps / vibehost whoami（或 list_workspaces）。硬编码过期的 ID 会导致失败；每次都应实时查询。
• 先阅读 MCP 工具的架构——使用 MCP 路径时，各工具的参数结构可能不同，也会随时间演变。调用工具前，请先阅读其自身的 description；不要假定参数结构与本文档中的描述一致。
• 根据 error.code 而非 error.message 分支处理——错误代码采用稳定的 SCREAMING_SNAKE_CASE 格式；错误消息可能会改写。
• 边缘 WAF 阻止原始 Blob 上传——CLI 会保留 UPSTREAM_FAILED，但会添加 details.kind = "blob_upload_blocked"、文件路径，以及 --no-chunked 提示。请使用 vibehost deploy --no-chunked 重试；gzip Tarball 路径可避免检查原始文件字节的内容。

参考资料

• 部署指南：https://docs.vibehost.com/guides/quickstart
• CLI 参考：https://docs.vibehost.com/guides/cli
• MCP 服务：https://docs.vibehost.com/guides/mcp
• 错误代码：https://docs.vibehost.com/reference/errors