本页覆盖从接入仓库到自定义域名上线的完整流程，同时提供 CLI、持续集成与开放 API 的速查参考。若需要更详细的说明，可联系技术支持获取完整版文档。
幻云部署支持三种接入方式，选择最符合你团队习惯的一种即可。三种方式产出的部署结果完全一致。
# 1. 在控制台新建项目并授权代码仓库（GitHub / GitLab / Gitee / 自建 Git） # 2. 关联分支后，任意一次推送都会自动触发构建与发布 $ git add . $ git commit -m "feat: 首页改版" $ git push origin main # 幻云自动完成：安装依赖 → 构建 → 资源优化 → 边缘分发 → 证书校验
# 安装幻云 CLI（支持 macOS / Linux / Windows） $ npm i -g @hydeploy/cli # 登录并关联项目 $ hydeploy login $ hydeploy init # 构建并发布到生产环境 $ hydeploy deploy --prod ✔ 构建完成 24.1s ✔ 已分发至 328 个边缘节点 ✔ 部署成功 https://www.example.com
# 无需代码仓库，直接上传已构建好的目录（适合临时活动页 / 静态站点） $ hydeploy deploy ./dist --prod # 在控制台「项目 - 手动上传」中拖入压缩包同样可行 # 单包上限 500 MB，超过 5000 个文件建议使用 CLI
使用邮箱注册幻云账号，在控制台点击「新建项目」，选择要部署的代码仓库。
授权代码平台后，幻云会自动读取仓库结构并推荐构建命令与产物目录，确认即可。
点击「立即部署」，或在本地向目标分支推送一次提交，构建将自动开始。
在项目设置的域名页添加自定义域名并配置 CNAME 解析，证书会自动签发完成。
首次部署建议先使用免费额度验证构建配置与访问效果，确认无误后再绑定正式域名。
幻云 CLI 覆盖日常研发中最常用的操作，可以嵌入本地脚本或持续集成流程，也支持在本地启动与线上一致的预览环境。
| 命令 | 说明 |
|---|---|
| hydeploy login | 登录并授权本机 CLI 访问幻云账号 |
| hydeploy init | 为当前项目生成配置模板并关联远程项目 |
| hydeploy dev | 在本地启动与线上一致的边缘预览环境 |
| hydeploy deploy --prod | 构建并发布到生产环境 |
| hydeploy rollback v247 | 将线上版本回滚到指定历史版本 |
| hydeploy logs --follow | 实时查看构建与访问日志 |
| hydeploy metrics --since 1h | 查看最近一小时的性能与错误指标 |
| hydeploy domain add example.com | 为项目添加自定义域名 |
# 本地拉起边缘预览环境，环境变量与线上一致
$ hydeploy dev --port 4000
✔ 已载入生产环境变量（密码字段已脱敏）
✔ 边缘函数已注入本地模拟运行时
➜ 访问 http://localhost:4000
# 查看历史版本 $ hydeploy list --limit 5 v248 2025-12-18 09:41 当前生效 v247 2025-12-17 18:20 v246 2025-12-17 15:02 # 回滚到指定版本（通常 2 秒内完成） $ hydeploy rollback v247 ✔ 已切换线上版本至 v247
如果团队已有流水线，可以通过幻云提供的官方 Action 或直接调用 CLI 完成部署，构建阶段的产物与幻云托管构建完全一致。
# .github/workflows/deploy.yml name: Deploy to HYDeploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci && npm run build - uses: hydeploy/actions-deploy@v3 with: token: ${{ secrets.HYDEPLOY_TOKEN }} project: mall-web prod: true
# .gitlab-ci.yml stages: [build, deploy] build: stage: build script: - npm ci - npm run build artifacts: paths: [dist] deploy: stage: deploy only: [main] script: - npm i -g @hydeploy/cli - hydeploy deploy ./dist --prod --token $HYDEPLOY_TOKEN
请将访问令牌配置在代码平台的加密变量中，不要写入仓库文件。令牌可在控制台「组织设置 - 访问令牌」中生成与吊销。
域名绑定完成后，幻云会自动完成证书签发、续期与 HTTPS 强制跳转，无需手工上传证书或维护续期脚本。
# 在域名服务商添加如下解析记录 类型 主机记录 记录值 TTL CNAME www edge.hydeploy.cn. 600 # 若主域名需要直达，请使用 A 记录或域名服务商提供的 CNAME 打平能力
$ hydeploy domain add www.example.com ✔ 已添加域名 www.example.com ➜ 请在域名服务商添加 CNAME：edge.hydeploy.cn. ⏳ 等待解析校验… ✔ 解析校验通过，证书签发完成（Let's Encrypt / 通配符证书）
同一域名同时存在 A 记录与 CNAME 记录时，解析结果不确定。添加 CNAME 前请先删除该主机记录下的 A 记录。
在仓库根目录放置 hydeploy.json 可以精确控制构建行为。不配置时幻云会依据框架类型自动推导，绝大多数项目无需手动配置。
| 字段 | 类型 | 说明 |
|---|---|---|
| framework | string | 框架标识，如 vite、next、nuxt、astro、hugo；留空则自动识别 |
| build | string | 构建命令，默认读取 package.json 中的 build 脚本 |
| output | string | 构建产物的相对目录，默认 dist |
| install | string | 依赖安装命令，默认 npm ci，可改为 pnpm / yarn |
| node | string | 构建使用的 Node 版本，支持 14 至 22 |
| env | object | 构建期环境变量，敏感值建议放在控制台的加密变量中 |
| headers | object | 自定义响应头，用于安全策略与缓存控制 |
| redirects | array | 重定向与改写规则，支持通配符与状态码 |
| cleanUrls | boolean | 是否去除 URL 中的 .html 后缀，默认开启 |
| ignore | array | 忽略上传的文件或目录，减少无效分发 |
{
"framework": "vite",
"install": "pnpm install --frozen-lockfile",
"build": "pnpm build",
"output": "dist",
"node": "20",
"cleanUrls": true,
"ignore": ["**/*.map", "docs/**"],
"headers": {
"X-Frame-Options": "SAMEORIGIN",
"Referrer-Policy": "strict-origin-when-cross-origin"
},
"redirects": [
{ "source": "/old/:path*", "destination": "/new/:path*", "status": 301 }
]
}
开放 API 覆盖项目、部署、域名与指标等核心资源的操作，可用于构建内部发布平台或对接企业审批系统。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v3/projects | 获取组织下的项目列表 |
| POST | /v3/projects/:id/deployments | 触发一次新的部署 |
| GET | /v3/deployments/:id | 查询部署状态与构建日志 |
| POST | /v3/deployments/:id/rollback | 将项目回滚至指定部署版本 |
| GET | /v3/projects/:id/metrics | 获取性能与错误率指标 |
| POST | /v3/domains | 添加自定义域名并触发证书签发 |
所有接口均通过请求头中的 Bearer 令牌鉴权。令牌在控制台「组织设置 - 访问令牌」中创建，可按项目与环境限定权限范围。
$ curl -X POST https://api.hydeploy.cn/v3/projects/mall-web/deployments \
-H "Authorization: Bearer $HYDEPLOY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ref":"main","prod":true,"message":"首页改版上线"}'
{
"id": "dpl_8f3a91c4",
"project": "mall-web",
"state": "READY",
"duration": 24.1,
"url": "https://www.example.com",
"createdAt": "2025-12-18T09:41:02+08:00"
}
接口默认限流为每令牌每分钟 600 次请求，如需提高配额，可在控制台提交申请或联系客户成功经理。
以下是接入过程中咨询频率较高的问题，如果仍未解决，欢迎直接联系技术支持团队。
自建服务器需要承担采购、系统运维、证书续期、负载均衡与容灾等一系列工作，且单机房难以覆盖全国与海外用户。幻云部署把这些能力封装为标准服务，开发者只需推送代码，构建、分发、加速、证书、监控全部自动完成，通常可以将上线准备时间从数天压缩到数分钟。
绝大多数情况下无需改动。幻云支持 Vue、React、Angular、Nuxt、Next.js、Astro、Vite、Hexo、Hugo 等主流框架的自动识别；如果项目构建流程特殊，也可以通过 hydeploy.json 自定义构建命令、产物目录与 Node 版本。
团队版及以上方案支持绑定自定义域名与泛域名。在控制台添加域名后，按提示配置一条 CNAME 解析记录即可，幻云会自动为该域名签发并续期 HTTPS 证书，无需手工上传证书文件。
不会自动扣费。流量或配额接近上限时，幻云会提前通过邮件与站内消息提醒，达到上限后站点仍可访问，但会暂停新的部署直到升级方案或下个计费周期重置，避免产生不可预期的费用。
国内节点数据存储于中国大陆多可用区，幻云已完成相关备案与安全评估，支持按需签署数据处理协议（DPA）。对于有更高合规要求的客户，企业版提供私有化 / 混合云部署，代码与数据完全保留在客户自有环境中。