文档中心

全站加速

开发指南

IGA Pages CLI 使用手册

IGA Pages CLI（@iga-pages/cli）是 IGA Pages 平台的命令行工具，用于在终端中完成项目的本地开发、部署上线与项目管理等操作。通过 CLI，您可以在本地启动带 Functions 支持的开发服务器，也可以一条命令将项目部署到火山引擎全站加速（DCDN）网络。

环境要求

依赖	最低版本
Node.js	>= 20

安装

全局安装：

npm install -g @iga-pages/cli

验证安装：

# 查看版本
iga -v

# 查看帮助
iga -h

快速开始

以下流程帮助您在 5 分钟内完成“安装 → 登录 → 本地开发 → 部署上线”的端到端体验。

# 1. 安装 CLI
npm install -g @iga-pages/cli

# 2. 登录（将自动打开浏览器完成认证）
iga login

# 3. 进入项目目录，关联 IGA Pages 项目（支持关联已有项目、创建并关联新项目）
cd your-project
iga pages link

# 4. （可选）启动本地开发服务器
iga pages dev

# 5. 开发完成后，部署到线上
iga pages deploy

部署成功后，CLI 会输出线上访问地址，打开即可查看效果。

命令参考

iga login [--remote] [--accessKey <AK>] [--secretKey <SK>]

参数

参数	类型	说明
`--remote`	`boolean`，可选	启用设备授权码登录，适用于云端开发容器、SSH 会话等无法在本机打开浏览器的环境；与 `--accessKey`／`--secretKey` 互斥
`--accessKey`	`string`，可选	火山引擎 Access Key，与 `--secretKey` 配合使用
`--secretKey`	`string`，可选	火山引擎 Secret Key，与 `--accessKey` 配合使用

登录方式说明

浏览器交互登录（默认）：直接执行 iga login，CLI 自动在本机打开浏览器完成认证，适用于本地开发。
设备授权码登录（远程）：执行 iga login --remote，CLI 在终端打印一个验证地址和一段短验证码；在任意可访问浏览器的设备上打开该地址、输入验证码并确认授权，CLI 会自动轮询并在授权完成后写入本地凭证。适用于云端开发容器、SSH 远程终端等无本机浏览器、但仍有人工操作的环境。
AK/SK 非交互登录：执行 iga login --accessKey <AK> --secretKey <SK>，无需交互，适用于持续集成等自动化场景。

示例

# 浏览器登录（默认方式，适用于本地开发）
iga login

# 设备授权码登录（远程，适用于云端容器/SSH 等无浏览器环境）
iga login --remote

# AK/SK 登录
iga login --accessKey <YOUR_AK> --secretKey <YOUR_SK>

iga logout

退出当前已登录的账号，清除本地凭证。
语法

iga logout

iga whoami

查看当前已登录的账号信息。
语法

iga whoami

iga switch

切换到其他火山引擎账号，执行后需重新登录。
语法

iga switch

iga pages link

将当前目录关联到一个 IGA Pages 项目。关联后，dev、deploy 以及 integration、env 命令都将自动对该项目生效。
语法

iga pages link [--project <idOrName>]

参数

参数	类型	说明
`--project`	`string`，可选	指定要关联的项目，按项目 ID 优先匹配，匹配失败再按项目名称匹配。用于无交互环境（如 IDE 插件、CI）下的非交互式直连，跳过交互式选择直接完成关联

示例

# 交互式关联（默认）
iga pages link

# 非交互式直连，指定项目名称或 ID（重名时建议传 ID）
iga pages link --project my-project-name
iga pages link --project 123456-abcd-...

注意事项

如果平台上尚无对应项目，CLI 会引导您创建一个新项目。link 仅完成项目的创建与关联，不会触发部署；首次部署请执行 iga pages deploy。
关联过程中，CLI 会自动检测项目所用的前端框架，用于后续构建与集成变量前缀的适配。

iga pages dev

启动本地开发服务器。服务器默认监听 3000 端口，将 /api/* 路径的请求交由 Functions 处理，其余请求透明代理至前端开发服务器（如 Vite、Next.js 等），实现前后端联调。
语法

iga pages dev [-p <port>]

参数

参数	类型	默认值	说明
`-p`	`number`，可选	`3000`	指定开发服务器监听端口

示例

# 使用默认端口 3000 启动
iga pages dev

# 指定端口 8080
iga pages dev -p 8080

注意事项

该命令会读取 package.json 的 dev 命令进行启动。请勿在 package.json 中配置 iga pages dev。
修改 api/ 目录下的文件后，路由自动重载，无需重启服务器。
Functions 采用文件系统路由：api/hello.js → /api/hello。
支持 Express 和 Koa 框架的集成开发模式。

iga pages deploy

将项目部署到 IGA Pages 平台。CLI 会根据项目的 Git 状态自动选择部署方式。
语法

iga pages deploy [-l, --logs]

参数

参数	类型	默认值
`-l, --logs`	`boolean`，可选	`false`

部署策略

条件	部署方式
项目有 GitHub 远程仓库且已在平台授权	从 Git 仓库拉取代码并构建部署
项目无 Git 仓库或未授权	将项目代码压缩为 ZIP 上传部署

注意事项

如果还没完成 IGA Pages 项目关联，CLI 会创建一个新项目然后部署。
首次部署时，CLI 会自动检测项目所用框架并应用对应的默认构建配置。
项目代码 ZIP 包上限为 1024 MB。
单个项目最多保留 10 个历史部署版本，超限后最旧的部署将被自动删除。
部署产物将通过火山引擎全站加速（DCDN）分发，支持中国大陆及海外加速区域。

iga pages inspect

查看指定部署的详情或其构建日志，可用于观察一次部署在初始化、构建、部署三阶段的进展与结果。
语法

iga pages inspect <deployment-id> [-p, --project <idOrName>] [-l, --logs] [--wait] [--timeout <duration>] [-F, --format json]

参数

参数	类型	默认值	说明
`<deployment-id>`	`string`，必填	无	要查看的部署 ID
`-p, --project`	`string`，可选	无	校验该部署所属的项目（按项目 ID 优先匹配，匹配失败再按名称匹配）；不指定也可查看，仅用于确认部署归属
`-l, --logs`	`boolean`，可选	`false`	展示该部署的完整构建日志（按初始化、构建、部署三阶段）
`--wait`	`boolean`，可选	`false`	持续等待直至该部署到达终态（成功或失败）后再返回
`--timeout`	`string`，可选	`3m`	与 `--wait` 配合使用，设置等待的超时时长（如 `3m`、`30s`）
`-F, --format`	`string`，可选	无	输出格式，指定 `json` 时以 JSON 输出，便于脚本消费

示例

# 查看指定部署的详情
iga pages inspect <deploymentId>

# 查看指定部署的完整构建日志
iga pages inspect <deploymentId> --logs

# 等待部署到达终态（最多等待 5 分钟）后返回
iga pages inspect <deploymentId> --wait --timeout 5m

# 以 JSON 格式输出，便于脚本处理
iga pages inspect <deploymentId> --format json

iga pages list / iga pages ls

查询项目或部署列表。命令会根据当前上下文自动判断查询内容：

在已关联项目的目录下执行，或指定了项目参数：列出该项目的近期部署，包含部署 ID、状态、预览地址与相对时间；Git 项目还会包含分支与提交信息。
未关联且未指定项目：列出当前账号下的全部项目，便于选择项目名称或 ID 用于关联。

语法

iga pages list [project]
iga pages ls [project]

参数

参数	类型	说明
`[project]`	`string`，可选	项目名称或 ID；省略时按当前目录的关联信息判断

示例

# 当前已关联项目的近期部署；未关联则列出全部项目
iga pages list

# 指定项目（名称或 ID）的近期部署
iga pages list my-project

iga pages preview

获取某次部署的预览访问地址。部署列表中返回的预览域名为裸域名，浏览器直接访问会被站点保护拦截；本命令会解析出带访问凭证的合法预览地址。
语法

iga pages preview [project] [--deployment <deployId>]

参数

参数	类型	说明
`[project]`	`string`，可选	项目名称或 ID；省略时按当前目录的关联信息判断
`--deployment`	`string`，可选	指定部署 ID；省略时取该项目最新一次部署

示例

# 当前关联项目的最新一次部署预览地址
iga pages preview

# 指定项目的最新部署
iga pages preview my-project

# 指定具体部署
iga pages preview --deployment <deployId>

iga pages logs

查询项目函数（Functions）的运行时日志，用于排查线上请求处理的异常与调用情况。
语法

iga pages logs [deployment-id] [-p, --project <idOrName>] [-d, --deployment <deployId>] [--since <time>] [--until <time>] [-n, --limit <number>] [--content <text>] [--level <level>] [-j, --json]

参数

参数	类型	默认值	说明
`[deployment-id]`	`string`，可选	无	指定要查询运行时日志的部署 ID；省略时按当前目录关联信息判断
`-p, --project`	`string`，可选	无	指定项目名称或 ID
`-d, --deployment`	`string`，可选	无	指定部署 ID
`--since`	`string`，可选	近 24 小时	查询起始时间，支持 ISO 时间或相对值（如 `1h`、`30m`、`7d`）
`--until`	`string`，可选	当前时间	查询结束时间，支持 ISO 时间或相对值
`-n, --limit`	`number`，可选	`100`	返回的日志条数上限
`--content`	`string`，可选	无	按日志内容关键字过滤
`--level`	`string`，可选	无	按日志级别过滤（`info` / `debug` / `warn` / `error`）
`-j, --json`	`boolean`，可选	`false`	以 JSON Lines 格式输出，便于脚本消费

示例

# 查询当前关联项目最近 24 小时的运行时日志
iga pages logs

# 查询最近 1 小时内 error 级别的日志
iga pages logs --since 1h --level 'error'

# 按关键字过滤并限制条数
iga pages logs --content 'timeout' -n 50

# 以 JSON Lines 输出，便于脚本处理
iga pages logs --json

注意事项

--since / --until 均支持 ISO 时间与相对值（如 1h、30m、7d）；不指定时默认查询近 24 小时。
查询时间范围最长为 7 天，--since 与 --until 的跨度超过 7 天将报错。
--content 与 --level 可组合使用，缩小排查范围。

iga pages integration

管理当前 IGA Pages 项目与外部服务的集成绑定。目前支持绑定火山引擎 Supabase，绑定后 Supabase 工作空间（Workspace）的连接信息会以环境变量形式自动注入项目。集成的操作背景与控制台入口，请参见集成火山引擎 Supabase。

说明

使用 integration 命令前，请先通过 iga pages link 关联项目，并完成火山引擎 Supabase 的跨服务授权。

iga pages integration link

为当前项目创建一个集成绑定。
语法

iga pages integration link <integration-name> [options]

参数

参数	类型	说明
`<integration-name>`	`string`，必填	集成绑定的名称，用于标识该绑定。
`--product`	`string`，可选	集成的产品类型，默认 `volc_supabase`（火山引擎 Supabase）。
`--region`	`string`，可选	Supabase 工作空间所在地域。
`--resource`	`string`，可选	要绑定的 Supabase 资源（工作空间）。
`--branch`	`string`，可选	要绑定的 Supabase 分支。
`--framework-prefix`	`string`，可选	注入客户端可见环境变量时使用的框架变量前缀（如 Next.js 的 `NEXT_PUBLIC_`、Vite 的 `VITE_`）。未指定时按检测到的框架自动填充。
`--prefix`	`string`，可选	注入环境变量的统一前缀。当一个 Pages 项目绑定多个 Supabase 时，用于避免变量名冲突。
`--yes`	`boolean`，可选	跳过交互确认。
`--format`	`string`，可选	输出格式。

iga pages integration unlink

解除当前项目的一个集成绑定，同时移除该绑定注入的环境变量。
语法

iga pages integration unlink <integration-name> [options]

参数

参数	类型	说明
`<integration-name>`	`string`，必填	要解除的集成绑定名称。
`--product`	`string`，可选	集成的产品类型，默认 `volc_supabase`。
`--resource`	`string`，可选	绑定的 Supabase 资源（工作空间）。
`--branch`	`string`，必填	绑定的 Supabase 分支。
`--yes`	`boolean`，可选	跳过交互确认。
`--format`	`string`，可选	输出格式。

iga pages integration list

列出当前项目的所有集成绑定。
语法

iga pages integration list

输出包含以下列：Name（绑定名称）、Integration（集成标识）、Product（产品类型）、Resource（资源 / 工作空间）、Branch（分支）、Env Prefix（环境变量前缀）。

iga pages env

管理当前 IGA Pages 项目的环境变量。可用于查看、增删改项目级变量，以及将线上变量拉取到本地。

注意

由集成绑定（如火山引擎 Supabase）自动注入的环境变量为只读，不能通过 env update 或 env remove 修改或删除。如需移除，请使用 iga pages integration unlink 解除对应绑定。

iga pages env list

列出当前项目的所有环境变量。别名 iga pages env ls。
语法

iga pages env list

iga pages env add

新增一个环境变量。
语法

iga pages env add <name> --value <value>

参数

参数	类型	说明
`<name>`	`string`，必填	环境变量名。
`--value`	`string`，必填	环境变量值。

iga pages env update

更新一个已有环境变量的值。
语法

iga pages env update <name> --value <value>

参数

参数	类型	说明
`<name>`	`string`，必填	要更新的环境变量名。
`--value`	`string`，必填	新的环境变量值。

说明

无法更新由集成绑定注入的环境变量。

iga pages env remove

删除一个环境变量。别名 iga pages env rm。
语法

iga pages env remove <name>

参数

参数	类型	说明
`<name>`	`string`，必填	要删除的环境变量名。
`--yes`	`boolean`，可选	跳过交互确认。

说明

无法删除由集成绑定注入的环境变量，如需移除请使用 iga pages integration unlink。

iga pages env pull

将线上项目的环境变量拉取到本地，写入当前目录的 .env.local 文件，便于本地开发调试。
语法

iga pages env pull

常见问题

Q1：`iga login` 打开浏览器后页面空白或无法跳转？

确认本地网络可正常访问火山引擎平台。如果处于代理或受限网络环境，建议改用 AK/SK 方式登录：

iga login --accessKey <AK> --secretKey <SK>

Q2：`iga pages dev` 端口被占用怎么办？

使用 -p 参数指定其他端口：

iga pages dev -p 8080

Q3：部署时提示项目代码包超出大小限制？

项目 ZIP 包上限为 1024 MB。请检查是否将 node_modules 或大型资源文件误包含在部署内容中，建议通过 .gitignore 排除不必要的文件。

Q4：如何查看历史部署记录？

单个项目最多保留 10 个部署版本。历史部署记录及版本回滚操作可在 IGA Pages 控制台的项目详情页 → 部署记录标签页中查看和管理。

Q5：在 GitHub Actions 中部署报错 `GitHub account "xxx" is not authorized`？

如果平台检测到当前项目是一个 GitHub 仓库，它会默认尝试从云端拉取代码部署。此时需要您先前往 IGA Pages 控制台完成 GitHub 账号授权，确保平台有权限访问该仓库，然后再重新触发部署。

Q6：Functions 的路由规则是什么？

Functions 使用文件系统路由。将文件放置在项目的 api/ 目录下，文件路径即为 API 路径：

文件路径	API 路径	路由类型
`api/hello.js`	`/api/hello`	静态路由
`api/users/[id].js`	`/api/users/:id`	动态路由
`api/[[default]].js`	`/api/*`（Catch-all）	通用匹配

详细路由规则请参阅 IGA Pages IGA Pages Functions 开发文档。

最近更新时间：2026.09.04 15:44:44

这个页面对您有帮助吗？

有用

无用

全站加速

环境要求 #

安装 #

快速开始 #

命令参考 #

iga login #

iga logout #

iga whoami #

iga switch #

iga pages link #

iga pages dev #

iga pages deploy #

iga pages inspect #

iga pages list / iga pages ls #

iga pages preview #

iga pages logs #

iga pages integration #

iga pages integration link

iga pages integration unlink

iga pages integration list

iga pages env #

iga pages env list

iga pages env add

iga pages env update

iga pages env remove

iga pages env pull

常见问题 #

Q1：iga login 打开浏览器后页面空白或无法跳转？ #

Q2：iga pages dev 端口被占用怎么办？ #

Q3：部署时提示项目代码包超出大小限制？ #

Q4：如何查看历史部署记录？ #

Q5：在 GitHub Actions 中部署报错 GitHub account "xxx" is not authorized？ #

Q6：Functions 的路由规则是什么？ #

环境要求

安装

快速开始

命令参考

iga login

iga logout

iga whoami

iga switch

iga pages link

iga pages dev

iga pages deploy

iga pages inspect

iga pages list / iga pages ls

iga pages preview

iga pages logs

iga pages integration

iga pages env

常见问题

Q1：`iga login` 打开浏览器后页面空白或无法跳转？

Q2：`iga pages dev` 端口被占用怎么办？

Q3：部署时提示项目代码包超出大小限制？

Q4：如何查看历史部署记录？

Q5：在 GitHub Actions 中部署报错 `GitHub account "xxx" is not authorized`？

Q6：Functions 的路由规则是什么？