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

环境要求 #

安装 #

全局安装：

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 #

登录 IGA Pages 平台。支持浏览器交互登录和 AK/SK 非交互登录两种方式。
语法

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

参数

示例

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

# 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 命令将自动对该项目生效。
语法

iga pages link

注意事项
如果平台上尚无对应项目，CLI 会引导您创建一个新项目。

iga pages dev #

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

iga pages dev [-p <port>]

参数

示例

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

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

注意事项

• 修改 api/ 目录下的文件后，路由自动重载，无需重启服务器。
• Functions 采用文件系统路由：api/hello.js → /api/hello。
• 支持 Express 和 Koa 框架的集成开发模式。

iga pages deploy #

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

iga pages deploy

部署策略

注意事项

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

常见问题 #

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 路径：

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