iga-pages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

IGA Pages Skill

IGA Pages 技能

Two areas: CLI (

iga

tool for auth, link, dev, build, deploy) and Project development (functions, API routes).

Run

iga <command> -h

for full flag details.

分为两大板块：CLI（用于认证、关联、开发、构建、部署的

iga

工具）和项目开发（函数、API路由）。

运行

iga <command> -h

查看完整的参数详情。

Critical: CLI Version

重要提示：CLI版本

The

@iga-pages/cli

version must be >= 1.0.3. Check with

iga --version

; if it's older (or not installed), upgrade before running any other command:

bash

npm i -g @iga-pages/cli@latest

@iga-pages/cli

版本必须**≥1.0.3**。可通过

iga --version

查看当前版本；若版本过低（或未安装），请先升级再执行其他命令：

bash

npm i -g @iga-pages/cli@latest

Critical: Framework Compatibility

重要提示：框架兼容性

Supported frameworks: Next.js, Vite, Vue CLI, Create React App, Angular, Hexo, Docusaurus, VitePress, VuePress, Hugo. Frameworks not in this list (e.g. Nuxt, Remix, Astro) are unsupported — proactively inform the user before proceeding.

Pure static assets (plain HTML/JS/CSS) can also be deployed — the project root is used as the output directory by default.

支持的框架包括：Next.js、Vite、Vue CLI、Create React App、Angular、Hexo、Docusaurus、VitePress、VuePress、Hugo。未在此列表中的框架（如Nuxt、Remix、Astro）暂不支持——在操作前需主动告知用户。

纯静态资源（纯HTML/JS/CSS）也可部署——默认将项目根目录作为输出目录。

Critical: Login Authentication

重要提示：登录认证

Before any deploy or link command, authenticate with

iga login

. The login method depends on the environment:

Local IDE (VS Code, TRAE desktop, etc.) → browser login:
bash
```
iga login
```

Wait for the user to complete browser auth. The CLI prints a success message when done.

Remote / headless environment (SSH, Cowork, CI/CD, cloud dev container, etc.) → AK/SK login:
bash
```
iga login --accessKey <YOUR_AK> --secretKey <YOUR_SK>
```
Browser-based login is unavailable in headless environments; AK/SK is the only option. Obtain AK/SK from the Volcengine IAM console.

To determine the environment: if the session has no display or browser access (e.g.,

$SSH_CONNECTION

is set, running inside a container, or the user mentions they are on a remote machine), default to AK/SK login. Otherwise, prefer browser for its simplicity.

在执行任何部署或关联命令前，需通过

iga login

完成认证。登录方式取决于运行环境：

本地IDE（VS Code、TRAE桌面版等）→ 浏览器登录：
bash
```
iga login
```

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

远程/无头环境（SSH、Cowork、CI/CD、云开发容器等）→ AK/SK登录：
bash
```
iga login --accessKey <YOUR_AK> --secretKey <YOUR_SK>
```
无头环境下无法使用浏览器登录，AK/SK是唯一可选方式。 AK/SK可从火山引擎IAM控制台获取。

环境判断方式：若会话无显示或浏览器访问权限（如已设置

$SSH_CONNECTION

、在容器内运行，或用户提及处于远程机器），默认使用AK/SK登录；否则优先选择更简便的浏览器登录。

Critical: Working Directory

重要提示：工作目录

All

iga

commands must run inside the project root. Scaffolding tools (

create-next-app

npm create vite

hugo new site

, etc.) create a subdirectory — you must
cd
into it before any

iga

command:

bash

npx create-next-app@latest my-app --yes
cd my-app && iga pages deploy --name my-app

所有

iga

命令必须在项目根目录内执行。脚手架工具（如

create-next-app

、

npm create vite

、

hugo new site

等）会创建子目录——执行任何

iga

命令前必须先
cd
进入该子目录：

bash

npx create-next-app@latest my-app --yes
cd my-app && iga pages deploy --name my-app

Quick Reference

快速参考

bash

npm i -g @iga-pages/cli

iga login                         # local IDE: opens browser
iga login --accessKey <AK> --secretKey <SK>  # remote/headless: AK/SK login

bash

npm i -g @iga-pages/cli

iga login                         # local IDE: opens browser
iga login --accessKey <AK> --secretKey <SK>  # remote/headless: AK/SK login

new project

iga pages deploy --name <my-app> # deploy (auto-creates project on first run)

project already linked

iga pages deploy

iga pages link # link to existing project without deploying iga pages dev # local dev server iga pages build # build for production


- **deploy** auto-detects GitHub remote → Git deploy; otherwise → upload deploy. Only GitHub is supported for Git integration.
- If deploy output includes a preview URL with `?iga_token=...&iga_time=...`, share that **full** URL (query included); omitting it can break access.

iga pages deploy

iga pages link # link to existing project without deploying iga pages dev # local dev server iga pages build # build for production


- **deploy**命令会自动检测GitHub远程仓库→采用Git部署；否则→采用上传部署。目前仅支持GitHub作为Git集成平台。
- 若部署输出包含带有`?iga_token=...&iga_time=...`的预览URL，请分享**完整**URL（包含查询参数）；省略参数可能导致访问失败。

Anti-Patterns

反模式

CLI

Running
```
iga
```
commands outside the project directory → always
```
cd
```
into the scaffolded subdirectory first
Deploy without login → always
```
iga login
```
first
Committing
```
.iga/
```
→ it's auto-gitignored, don't remove the entry
```
provider: "upload_v2"
```
with GitHub remote → delete
```
.iga/project.json
```
and redeploy to switch to Git deploy

CLI相关反模式

在项目目录外执行
```
iga
```
命令→需先
```
cd
```
进入脚手架创建的子目录
未登录就执行部署→需先执行
```
iga login
```
提交
```
.iga/
```
目录→该目录已自动被Git忽略，请勿移除忽略规则
已关联GitHub远程仓库但使用
```
provider: "upload_v2"
```
→删除
```
.iga/project.json
```
并重新部署即可切换为Git部署