Back to Details

edgeone-pages-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EdgeOne Pages Deployment Skill

EdgeOne Pages 部署技能

Deploy any project to EdgeOne Pages.
将任意项目部署至EdgeOne Pages。

⛔ Critical Rules (MUST follow — never skip)

⛔ 重要规则（必须遵守，切勿跳过）

  1. CLI version MUST be 
    1.2.30
    or higher    . If the installed version is lower, reinstall. Do NOT proceed with an outdated version.
  2. NEVER truncate the deploy URL. The 
    EDGEONE_DEPLOY_URL
    includes query parameters that are required for access. Always output the complete URL including all query string parameters — without them the page won't load.
  3. MUST ask the user to choose China or Global site before login. Never assume.
  4. MUST auto-detect the login method — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below.
  5. After token login, MUST ask if the user wants to save the token locally for future use.
  1. CLI版本必须为
    1.2.30
    或更高    。若已安装版本低于该要求，请重新安装。切勿使用过时版本进行操作。
  2. 绝不要截断部署URL。
    EDGEONE_DEPLOY_URL
    包含访问所需的查询参数。务必输出完整的URL，包括所有查询字符串参数——缺少这些参数页面将无法加载。
  3. 登录前必须询问用户选择中国站还是全球站。切勿自行假设。
  4. 必须自动检测登录方式——桌面环境下使用浏览器登录，无头/远程/CI环境下使用Token登录。请遵循下方的决策表。
  5. Token登录完成后，必须询问用户是否要将Token本地保存，以便后续使用。

Deployment Flow

部署流程

Run these checks first, then follow the decision table:
bash
undefined
先执行以下检查，再遵循决策表操作：
bash
undefined

Check 1: CLI installed and correct version?

检查1：CLI是否已安装且版本正确？

edgeone -v
edgeone -v

Check 2: Already logged in?

检查2：是否已登录？

edgeone whoami
edgeone whoami

Check 3: Project already linked?

检查3：项目是否已关联？

cat edgeone.json 2>/dev/null
cat edgeone.json 2>/dev/null

Check 4: Saved token exists?

检查4：是否存在已保存的Token？

cat .edgeone/.token 2>/dev/null
undefined
cat .edgeone/.token 2>/dev/null
undefined

Decision Table

决策表

CLI versionLogin statusAction
Not installed or version < 1.2.30—→ Go to Install CLI
≥ 1.2.30
✓		Logged in→ Go to Deploy
≥ 1.2.30
✓		Not logged in, has saved token→ Go to Deploy with Token (use saved token)
≥ 1.2.30
✓		Not logged in, no saved token→ Go to Login
CLI版本登录状态操作
未安装或版本 < 1.2.30—→ 跳转至安装CLI
≥ 1.2.30
✓		已登录→ 跳转至部署
≥ 1.2.30
✓		未登录，但存在已保存的Token→ 跳转至使用Token部署（使用已保存的Token）
≥ 1.2.30
✓		未登录，且无已保存的Token→ 跳转至登录

Install CLI

安装CLI

bash
npm install -g edgeone@latest
Verify: 
edgeone -v
must output 
1.2.30
or higher. If not, retry installation.
bash
npm install -g edgeone@latest
验证：
edgeone -v
必须输出
1.2.30
或更高版本。若未达到，请重新安装。

Login

登录

1. Ask the user to choose a site

1. 询问用户选择站点

You MUST ask before running any login command. Use the IDE's selection control (
ask_followup_question
):
Choose your EdgeOne Pages site:
  • China — For users in mainland China (console.cloud.tencent.com)
  • Global — For users outside China (console.intl.cloud.tencent.com)
执行任何登录命令前必须询问。使用IDE的选择控件（
ask_followup_question
）：
选择你的EdgeOne Pages站点：
  • 中国站 — 面向中国大陆用户（console.cloud.tencent.com）
  • 全球站 — 面向海外用户（console.intl.cloud.tencent.com）

2. Detect environment and choose login method

2. 检测环境并选择登录方式

ConditionMethod
Local desktop IDE (e.g. VS Code, Cursor, etc.)Browser Login
Remote / SSH / container / CI / cloud IDE / headlessToken Login
User explicitly requests tokenToken Login
条件方式
本地桌面IDE（如VS Code、Cursor等）浏览器登录
远程/SSH/容器/CI/云IDE/无头环境Token登录
用户明确要求使用TokenToken登录

Browser Login

浏览器登录

bash
undefined
bash
undefined

China site

中国站

edgeone login --site china
edgeone login --site china

Global site

全球站

edgeone login --site global

Wait for the user to complete browser auth. The CLI prints a success message when done.
edgeone login --site global

等待用户完成浏览器端认证。完成后CLI会打印成功消息。

Token Login

Token登录

Token login does NOT use 
edgeone login
. The token is passed directly in the deploy command via 
-t
.
Guide the user to get a token:
  1. Go to the console:
  2. Find API Token → Create Token → Copy it
⚠️ Remind the user: the token has account-level permissions. Never commit it to a repository.
Token登录不使用
edgeone login
命令。Token通过部署命令中的
-t
参数直接传入。
引导用户获取Token：
  1. 进入控制台：
  2. 找到API Token → 创建Token → 复制Token
⚠️ 提醒用户：该Token拥有账号级权限，切勿提交至代码仓库。

3. Offer to save the token locally

3. 提供Token本地保存选项

After the user provides a token, MUST ask:
Would you like to save this token locally for future deployments?
  • Yes — Save to 
    .edgeone/.token
    (auto-used next time)
  • No — Use for this deployment only
If Yes:
bash
mkdir -p .edgeone
echo "<token>" > .edgeone/.token
grep -q '.edgeone/.token' .gitignore 2>/dev/null || echo '.edgeone/.token' >> .gitignore
Tell the user: "✅ Token saved to 
.edgeone/.token
and added to 
.gitignore
."
用户提供Token后，必须询问：
是否要将该Token本地保存，以便未来部署使用？
  • 是 — 保存至
    .edgeone/.token
    （下次部署将自动使用）
  • 否 — 仅本次部署使用
若选择是：
bash
mkdir -p .edgeone
echo "<token>" > .edgeone/.token
grep -q '.edgeone/.token' .gitignore 2>/dev/null || echo '.edgeone/.token' >> .gitignore
告知用户：“✅ Token已保存至
.edgeone/.token
，并已添加至
.gitignore
。”

Deploy

部署

Browser-authenticated deploy

浏览器认证后的部署

bash
undefined
bash
undefined

Project already linked (edgeone.json exists)

项目已关联（存在edgeone.json）

edgeone pages deploy
edgeone pages deploy

New project (no edgeone.json)

新项目（无edgeone.json）

edgeone pages deploy -n <project-name>

`<project-name>`: auto-generate from the project directory name. The first deploy creates `edgeone.json` automatically.
edgeone pages deploy -n <project-name>

`<project-name>`：从项目目录名自动生成。首次部署会自动创建`edgeone.json`。

Token-based deploy

基于Token的部署

First check for a saved token:
bash
cat .edgeone/.token 2>/dev/null
  • Saved token found → use it, tell the user: "Using saved token from 
    .edgeone/.token
    "
  • No saved token → ask the user to provide one (see Token Login above)
bash
undefined
首先检查是否存在已保存的Token：
bash
cat .edgeone/.token 2>/dev/null
  • 找到已保存的Token → 使用该Token，并告知用户：“正在使用
    .edgeone/.token
    中保存的Token”
  • 无已保存的Token → 引导用户提供Token（参考上方Token登录部分）
bash
undefined

Project already linked

项目已关联

edgeone pages deploy -t <token>
edgeone pages deploy -t <token>

New project

新项目

edgeone pages deploy -n <project-name> -t <token>

The token already contains site info — no `--site` flag needed.

**After a successful deploy with a manually-entered token**, ask if the user wants to save it (see "Offer to save the token locally" above).
edgeone pages deploy -n <project-name> -t <token>

Token已包含站点信息 — 无需使用`--site`参数。

**若手动输入Token完成部署后**，询问用户是否要保存该Token（参考“提供Token本地保存选项”部分）。

Deploy to preview environment

部署至预览环境

bash
edgeone pages deploy -e preview
bash
edgeone pages deploy -e preview

Build behavior

构建行为

The CLI auto-detects the framework, runs the build, and uploads the output directory. No manual config needed.
CLI会自动检测框架，执行构建并上传输出目录。无需手动配置。

⚠️ Parse Deploy Output (Critical — read carefully)

⚠️ 解析部署输出（至关重要，请仔细阅读）

After 
edgeone pages deploy
succeeds, the CLI outputs:
[cli][✔] Deploy Success
EDGEONE_DEPLOY_URL=https://my-project-abc123.edgeone.cool?<auth_query_params>
EDGEONE_DEPLOY_TYPE=preset
EDGEONE_PROJECT_ID=pages-xxxxxxxx
[cli][✔] You can view your deployment in the EdgeOne Pages Console at:
https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deployment/xxxxxxx
Extraction rules:
FieldHow to extract⛔ Warning
Access URLFull value after 
EDGEONE_DEPLOY_URL=
MUST include the full query string (
?
and everything after it) — without these params the page won't load
Project IDValue after 
EDGEONE_PROJECT_ID=
—
Console URLLine after "You can view your deployment..."—
Show the user:
✅ Deployment complete!
  • Access URL: 
    https://my-project-abc123.edgeone.cool?<auth_query_params>
  • Console URL: 
    https://console.cloud.tencent.com/edgeone/pages/project/...
edgeone pages deploy
执行成功后，CLI会输出如下内容：
[cli][✔] Deploy Success
EDGEONE_DEPLOY_URL=https://my-project-abc123.edgeone.cool?<auth_query_params>
EDGEONE_DEPLOY_TYPE=preset
EDGEONE_PROJECT_ID=pages-xxxxxxxx
[cli][✔] You can view your deployment in the EdgeOne Pages Console at:
https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deployment/xxxxxxx
提取规则：
字段提取方式⛔ 注意事项
访问URL
EDGEONE_DEPLOY_URL=
后的完整值		必须包含完整的查询字符串（
?
及其后的所有内容）——缺少这些参数页面将无法加载
项目ID
EDGEONE_PROJECT_ID=
后的取值		—
控制台URL“You can view your deployment...”后的行内容—
展示给用户：
✅ 部署完成！
  • 访问URL：
    https://my-project-abc123.edgeone.cool?<auth_query_params>
  • 控制台URL：
    https://console.cloud.tencent.com/edgeone/pages/project/...

Error Handling

错误处理

ErrorSolution
command not found: edgeone
npm install -g edgeone@latest
Browser doesn't open during loginUse token login instead
"not logged in" error
edgeone whoami
to check, then re-login or use token
Auth error with tokenToken may be expired — regenerate at the console
Project name conflictUse a different name with 
-n
Build failureCheck logs — usually missing deps or bad build script
错误解决方案
command not found: edgeone
执行
npm install -g edgeone@latest
登录时浏览器未自动打开改用Token登录
“not logged in”错误执行
edgeone whoami
检查状态，然后重新登录或使用Token
Token认证错误Token可能已过期 — 前往控制台重新生成
项目名称冲突使用
-n
参数指定其他名称
构建失败检查日志 — 通常是缺少依赖或构建脚本错误

Appendix

附录

Edge/Node Functions

Edge/Node 函数

For projects needing server-side functions, run before first deploy:
bash
edgeone pages init
Pure static projects skip this.
对于需要服务端函数的项目，首次部署前执行：
bash
edgeone pages init
纯静态项目可跳过此步骤。

Local Development

本地开发

bash
edgeone pages dev    # http://localhost:8088/
bash
edgeone pages dev    # http://localhost:8088/

Environment Variables

环境变量

bash
edgeone pages env ls          # List all
edgeone pages env pull        # Pull to local .env
edgeone pages env add KEY val # Add
edgeone pages env rm KEY      # Remove
bash
edgeone pages env ls          # 列出所有环境变量
edgeone pages env pull        # 拉取至本地.env文件
edgeone pages env add KEY val # 添加环境变量
edgeone pages env rm KEY      # 删除环境变量

Project Linking

项目关联

bash
edgeone pages link
bash
edgeone pages link

Token Management

Token管理

TaskHow
Save tokenStored in 
.edgeone/.token
(auto-added to 
.gitignore
)
Update tokenDelete 
.edgeone/.token
, then deploy again — you'll be prompted to enter and save a new one
Use saved tokenAutomatic — the agent reads 
.edgeone/.token
before each token deploy
任务操作方式
保存Token存储在
.edgeone/.token
（自动添加至
.gitignore
）
更新Token删除
.edgeone/.token
，然后重新部署 — 系统会提示你输入并保存新Token
使用已保存的Token自动完成 — 代理会在每次Token部署前读取
.edgeone/.token

Command Reference

命令参考

ActionCommand
Install CLI
npm install -g edgeone@latest
Check version
edgeone -v
Login (China)
edgeone login --site china
Login (Global)
edgeone login --site global
View login info
edgeone whoami
Logout
edgeone logout
Switch account
edgeone switch
Init functions
edgeone pages init
Local dev
edgeone pages dev
Link project
edgeone pages link
Deploy
edgeone pages deploy
Deploy new project
edgeone pages deploy -n <name>
Deploy preview
edgeone pages deploy -e preview
Deploy with token
edgeone pages deploy -t <token>
操作命令
安装CLI
npm install -g edgeone@latest
检查版本
edgeone -v
登录（中国站）
edgeone login --site china
登录（全球站）
edgeone login --site global
查看登录信息
edgeone whoami
登出
edgeone logout
切换账号
edgeone switch
初始化函数
edgeone pages init
本地开发
edgeone pages dev
关联项目
edgeone pages link
部署
edgeone pages deploy
部署新项目
edgeone pages deploy -n <name>
部署预览环境
edgeone pages deploy -e preview
使用Token部署
edgeone pages deploy -t <token>