iga-pages

IGA Pages 技能

分为两个部分：CLI（使用 iga 工具进行身份验证、创建项目、开发、构建、部署、检查、环境配置和集成）和项目开发（函数、API 路由、Agent 和 Blob SDK）。

运行 iga <command> -h 查看完整的标志详情。

重要：CLI 版本

@iga-pages/cli 版本必须为 >= 1.1.9，Node.js 版本必须为 >= 20。使用 iga --version 检查；如果缺少 CLI 或版本较旧，请先安装或升级公开发布的包，再使用其他 iga 命令：

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

重要：框架兼容性

支持的公开框架：Next.js、Vite、Vue CLI、Create React App、Angular、Hexo、Docusaurus、VitePress、VuePress、Astro 和 Nuxt。不在此列表中的框架（例如 Remix）不受支持；请在继续之前告知用户。

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

重要：登录身份验证

执行远程操作（init、link、list、deploy、preview、inspect、logs、env 和 integration）之前，运行 iga whoami。如果现有登录有效，请继续使用。只有在凭据缺失、过期或被拒绝时才运行 iga login；应排查网络和服务错误，而不是将每次失败都视为需要重新登录。

确实需要登录时，登录方式取决于环境：

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

  iga login
  

  等待用户完成浏览器身份验证。完成后，CLI 会打印成功消息。

• 远程交互式终端（SSH、Cowork、云端开发容器等）→ 设备代码登录：

  iga login --remote
  

  CLI 会打印验证 URL 和短代码，然后在用户使用任意浏览器完成授权期间持续轮询。

• 无人值守自动化（CI/CD 或其他无法由人员完成授权的环境）→ AK/SK 登录：

  iga login --accessKey <YOUR_AK> --secretKey <YOUR_SK>
  

  从 火山引擎 IAM 控制台获取 AK/SK。

确定登录方式时：如果终端无法打开本地浏览器，但有人可以在其他位置完成授权，则使用 --remote；无人值守自动化才使用 AK/SK。其他情况下，优先使用默认的浏览器登录。--remote 和 AK/SK 不能同时使用。

重要：工作目录

在项目根目录内运行 pages link、dev、build 和 deploy 等项目级命令。脚手架工具（create-next-app、npm create vite、hugo new site 等）会创建子目录——运行这些命令前，必须使用 cd 进入该目录：

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

重要：使用归属

为此技能执行的每个 iga 命令添加标记，以便归属其用量。 此标记只标识技能及其版本，不包含任何用户数据。

无论子命令是什么，每次调用 iga 时都要添加进程范围的 VE_SKILL_ID 前缀。请在每条命令中内联设置，因为 Shell 状态可能无法 在命令之间保留：

VE_SKILL_ID=iga-pages/1.0.13 iga <command>

快速参考

iga --version                       # must be >= 1.1.9

iga whoami                        # check current login state; run this BEFORE login
iga login                         # local IDE: opens browser; only if whoami fails
iga login --remote                # remote interactive terminal; only if whoami fails
iga login --accessKey <AK> --secretKey <SK>  # unattended automation; only if whoami fails

## create an Agent project from a current template
iga pages init --type agent --list --json
iga pages init <directory> --type agent --template <ID>

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

iga pages link                     # create/associate a Pages project (does NOT deploy)
iga pages link --format=json       # list choices as JSON without changing state
iga pages link --yes --format=json # auto-link/create and return the result as JSON
iga pages dev                      # local dev server (REQUIRED when api/ exists — serves framework + /api/* together)
iga pages build                    # build for production

## environment variables (project-level, linked project required)
iga pages env list                 # list KEY names (values never shown)
iga pages env list --format=json   # as JSON
iga pages env add <NAME>           # add (--value <v> --yes for CI)
iga pages env update <NAME>        # update existing
iga pages env remove <NAME>        # remove (--yes to skip confirm)
iga pages env pull                 # write all project env to .env.local

## integrations (Supabase; linked project required)
iga pages integration list                  # bindings on this project
iga pages integration list --format=json    # as JSON
iga pages integration link supabase         # connect Volcengine Supabase
iga pages integration link supabase --format=json   # as JSON; returns next missing flag until all provided
iga pages integration unlink                # remove a binding
iga pages integration unlink --format=json --yes    # as JSON (requires --yes)

• Agent 项目与其他全栈项目使用相同的 pages dev、pages build 和 pages deploy 工作流；没有单独的 Agent 部署命令。
• 对于新项目，GitHub 远程仓库已授权时，部署会使用 Git 部署，否则会回退到上传部署。已关联的项目会保留其配置的提供方。Git 集成仅支持 GitHub。
• 如果部署输出包含带有 ?iga_token=...&iga_time=... 的预览 URL，请分享该完整 URL（包括查询参数）；省略它可能导致无法访问。

项目开发

• 框架检测、支持的版本以及所需的 Astro/Nuxt 集成： 请参阅 references/frameworks.md。
• API 路由和 Pages Functions：请参阅 references/functions.md。
• Agent Store、框架会话、Sandbox 生命周期以及面向模型的工具： 请参阅 references/agent-sdk.md。
• 持久的项目级对象存储和浏览器上传凭证： 请参阅 references/blob-sdk.md。

环境变量与集成

• 项目级环境变量（env list/add/update/remove/pull）：请参阅 references/env.md。
• 连接 Supabase（integration list/link/unlink）和部署编排顺序（link → integration → deploy），以及何时应移交给 byted-supabase skill：请参阅 references/integration.md。

检查与日志

• 部署状态、构建日志和历史运行时日志： 请参阅 references/logs.md。

反模式

CLI

• 在项目目录外运行 iga 命令 → 始终先 cd 进入脚手架生成的子目录
• 在未通过身份验证的会话中部署 → 先运行 iga whoami；只有失败时才运行 iga login
• 提交 .iga/ → 不要将其纳入源代码管理；link/deploy 通常会将 .iga/ 添加到 .gitignore，但这项更新尽力而为
• 存在 api/ 时，使用 npm run dev / vite / next dev / npm start 启动本地开发 → 使用 iga pages dev 以提供无服务器函数
• 将 package.json "scripts.dev" 设置为 iga pages dev → 会导致无限循环，因为 iga pages dev 本身会调用 package.json 中的 dev 脚本。请将 "scripts.dev" 保留为框架自身的开发命令（例如 next dev、vite）
• 在 link 之前运行 env / integration 命令 → 这些命令需要已链接的项目；请先运行 iga pages link
• 认为 env add/update/remove 会更改本地文件或立即生效 → 这些命令会编辑远程项目配置，并在下一次部署时生效；运行 iga pages env pull 以刷新 .env.local
• 尝试对由 Supabase 管理的变量执行 env update/env remove → 这些变量为只读；请通过 iga pages integration link/unlink 进行管理
• 集成可用时仍手动将 Supabase 密钥粘贴到 env add → 使用 iga pages integration link supabase，以自动同步连接变量
• 在浏览器代码或任意 Node.js 进程中导入 @iga-pages/agent 或 @iga-pages/blob → 仅在 IGA Pages Functions 或全栈框架服务器处理程序中使用它们