静态站点部署到边缘平台的一次完整记录

这个站本身就是部署在 EdgeOne Pages 上的。整个过程不复杂，但有几个点第一次做会卡一下，记下来备查。流程本身对其他同类平台（Vercel、Netlify、Cloudflare Pages）也大体通用。

为什么选边缘托管

纯静态站点其实随便找台 VPS 装个 Nginx 也能跑。选托管平台主要图三件事：

不用管服务器——没有系统更新、没有证书续期、没有磁盘满了要清日志。
自带 CDN 和 HTTPS——静态资源就近分发，证书自动签发续期。
部署即一条命令——本地敲一下，几十秒后线上就是新版本，出问题还能一键回滚到上一次部署。

代价是灵活性变差：需要自定义 Nginx 规则、要跑常驻进程、或者对文件系统有要求的场景，还是得回到自己的服务器。个人博客、文档站、落地页这类，托管平台基本是最优解。

准备工作

先装 CLI：

npm install -g edgeone@latest
edgeone -v

版本要注意。旧版本在非交互环境（CI、各种 agent、SSH 会话）里会因为等待终端输入而挂住，表现是命令跑到一半没有任何输出也不退出。遇到这种情况先确认版本，别急着 debug 别的。

两种登录方式

本地开发机上直接浏览器登录最省事：

edgeone login --site china    # 国内站
edgeone login --site global   # 国际站

这里有个容易踩的坑：浏览器可能会静默复用上一次的登录会话。如果之前登过国际站，现在要登国内站，页面可能直接就跳过登录了，CLI 显示成功但实际绑到了另一个账号，后面部署就会报鉴权错误。遇到就在登录页点「使用其他账号登录」，或者先把两边控制台都登出再来。

在没有浏览器的环境（CI runner、远程服务器、脚本里）就得用 token：

edgeone makers deploy -n my-site -t <token>

token 在控制台的 Pages 设置页创建。它是账号级权限，千万别提交到仓库里。如果要存本地，记得同时写进 .gitignore：

mkdir -p .edgeone
echo "<token>" > .edgeone/.token
grep -q '.edgeone/.token' .gitignore || echo '.edgeone/.token' >> .gitignore

部署

项目根目录下：

edgeone makers deploy -n my-site --json

CLI 会自动识别框架、跑构建、上传产物。纯静态项目没有构建步骤，直接上传目录。

--json 这个参数在脚本里很有用：正常输出带颜色码和进度条回车符，正则去解析很难受；加上之后最后一行是一个干净的 JSON，直接 jq 取字段就行。

{"status":"success","url":"https://my-site-xxxx.edgeone.cool?eo_token=…","projectId":"…"}

想先发到预览环境验证，再推正式：

edgeone makers deploy -e preview     # 预览
edgeone makers deploy -e production  # 正式

预览域名不是最终域名

部署完拿到的那个 xxx.edgeone.cool 链接，后面跟着一串 ?eo_token=…&eo_time=…。这两个查询参数是访问凭证，去掉就是 401。我第一次顺手把问号后面截掉发给别人，对方打开一片空白，找了半天才反应过来。

另外用 curl 直接请求这个地址可能会被重定向到 SSO 登录页，因为凭证校验依赖浏览器端的 JS。这不是部署失败，用真实浏览器打开完整链接就正常。

预览域名的定位就是「部署后快速自查」，不适合长期对外。要稳定公开访问，必须绑自己的域名。

绑定自定义域名

在控制台项目设置里添加域名，然后按提示在 DNS 服务商那边加解析记录（通常是一条 CNAME）。等 DNS 生效后平台会自动签发证书。

如果域名要在中国大陆提供服务，还需要完成 ICP 备案。这一步和技术无关但绕不过去，几个实际经验：

备案审核期间管局会实际访问你的域名，所以站点得先能打开、内容得和备案填写的信息对得上。
个人性质的备案，站点内容就应该是个人展示、技术笔记这类，不要出现商品、支付、会员注册、论坛这些经营性或强交互的功能。
备案号要放在页面底部，并且链接到工信部的查询站点。这是硬性要求，漏了会被驳回。

<a href="https://beian.miit.gov.cn/" target="_blank" rel="noopener">
  蜀ICP备xxxxxxxx号-x
</a>

几个报错

现象	原因 / 处理
命令卡在部署中不动	非 TTY 环境下没有动画输出，多数情况只是没有实时反馈而非卡死。用 `--json` 或放后台跑，别急着 Ctrl+C
项目数超出上限	账号有项目数量上限。去控制台删掉不用的，或者用 `-n` 指定一个已有项目名复用
登录成功但部署报鉴权失败	浏览器会话复用到了另一个站点/账号，重新登录并显式选择账号
项目名冲突	换个 `-n` 的值

接进 CI

把 token 放进仓库的 secrets，工作流里就是一步：

- name: Deploy
  run: |
    npm install -g edgeone@latest
    edgeone makers deploy -n my-site -t "$EO_TOKEN" --json
  env:
    EO_TOKEN: ${{ secrets.EDGEONE_TOKEN }}

推 main 自动发正式、推其他分支发预览，是比较顺手的一套配置。

小结

整套流程真正需要记住的其实就三条：CLI 版本别用旧的；预览链接的查询参数一个都不能少；要长期对外访问就老老实实绑域名走备案。剩下的平台都替你办了。