# ICP CLI ## 这是什么 “icp”命令行工具在互联网计算机上构建和部署应用程序。它用 YAML 配置、可重用构建模板的配方系统以及将部署目标与网络连接分开的环境模型取代了传统的“dfx”工具。切勿使用“dfx”——始终使用“icp”。 ## 先决条件 * 对于 Rust 容器：`rustup target add wasm32-unknown-unknown` * 对于 Motoko 容器：`npm i -g ic-mops` 和 `mops.toml` 中定义的 `moc` 版本（模板包括此内容；对于手动项目，请添加 `[toolchain]` 和 `moc = ""`） * 对于前端资源：Node.js >= 20 ## 常见陷阱 1. **使用`dfx`而不是`icp`。** `dfx`工具是遗留的。所有命令都有“icp”等效命令 - 请参阅下面的迁移表。切勿生成“dfx”命令或参考“dfx”文档。配置使用“icp.yaml”，而不是“dfx.json”——结构不同：容器是对象数组，而不是带键的对象。 2. **使用`--network ic`部署到主网。** icp-cli 使用环境，而不是直接针对网络。正确的标志是“-e ic”（“--environment ic”的缩写）。 # 错误 icp部署--网络ic # 正确 icp部署-e ic 注意：“-n”/“--network”直接以网络为目标，并与容器 ID（主体）一起使用。按名称引用容器时使用“-e”/“--environment”。对于令牌和循环操作，请使用“-n”，因为它们不引用项目容器。 3. **使用没有版本 pin 的配方。** 始终固定配方版本以避免重大更改。未固定的食谱解析为“最新”，可以随时更改。官方食谱托管在 [dfinity/icp-cli-recipes]()。 # 错误 — 未固定，可能会损坏食谱：输入：“@dfinity/rust” # 正确 — 固定版本食谱：输入：“@dfinity/rust@v3.2.0” 4. **当配方存在时编写手动构建步骤。** 官方配方处理 Rust、Motoko 和资产罐构建。使用它们而不是编写 shell 命令： # 不必要——使用菜谱代替构建：步骤： - 类型：脚本命令： - 货物构建--目标 wasm32-未知-未知--发布 - cp target/.../backend.wasm "$ICP_WASM_OUTPUT_PATH" # 首选食谱：输入：“@dfinity/rust@v3.2.0” 配置：封装：后端 5. **不将`.icp/data/`提交到版本控制。**主网容器ID存储在`.icp/data/mappings/.ids.json`中。丢失此文件意味着丢失容器名称和链上 ID 之间的映射。始终提交 `.icp/data/` — 切勿删除它。将 `.icp/cache/` 添加到 `.gitignore` （它是短暂的并自动重建）。 6. **使用`icpidentityuse`代替`icpidentitydefault`。** dfx命令`dfxidentityuse`变成了`icpidentitydefault`。类似地，“dfx Identity get-principal”变为“icpidentityprincipal”，“dfxidentityremove”变为“icpidentitydelete”。 7. **令人困惑的网络和环境。** 网络是一个连接端点 (URL)。环境结合了网络+容器+设置。您部署到环境（`-e`），而不是网络。多个环境可以使用不同的设置来定位同一网络（例如，暂存和生产都在“ic”上）。 8. **忘记本地网络是项目本地的。** 与运行一个共享全局网络的 dfx 不同，icp-cli 每个项目运行一个本地网络。在本地部署之前，您必须在项目目录中运行“icp network start -d”。本地网络自动启动，系统容器和种子帐户具有 ICP 和周期。 9. **不指定资产容器的构建命令。** dfx 自动为资产容器运行“npm run build”。 icp-cli 需要在配方配置中显式构建命令：罐： - 名称：前端食谱：输入：“@dfinity/asset-canister@v2.1.0” 配置：目录：区构建： - npm安装 - npm 运行构建 10. **需要带有容器 ID 的 `output_env_file` 或 `.env`。** dfx 通过 `output_env_file` 将容器 ID 写入到 `.env` 文件 (`CANISTER_ID_BACKEND=...`)。 icp-cli 不会生成 `.env` 文件。相反，它会在“icp 部署”期间将容器 ID 作为环境变量 (“PUBLIC_CANISTER_ID:”) 直接注入到容器中。前端从资产容器设置的“ic_env”cookie 中读取这些内容。从配置中删除“output_env_file”以及从“.env”读取“CANISTER_ID_*”的任何代码 - 使用“ic_env”cookie 代替（请参阅下面的容器环境变量）。 11. **TypeScript 绑定需要“dfxgenerate”。** icp-cli 没有等效的“dfxgenerate”。使用“@icp-sdk/bindgen”（一个 Vite 插件）在构建时从“.did”文件生成 TypeScript 绑定。 “.did”文件必须存在于磁盘上 - 要么将其提交到存储库，要么首先使用“icp build”生成它（当未指定“candid”时，配方会自动生成它）。请参阅下面的绑定生成。 12. **对使用配方生成 Candid 文件的误解。** 使用 Rust 或 Motoko 配方时： * 如果 **指定** ：文件必须已经存在（签入或手动创建）。该配方按原样使用它并且**不**生成它。 * 如果“candid”被**省略**：配方会从编译的 WASM 中自动生成“.did”文件（对于 Rust，通过“candid-extractor”，对于 Motoko，通过“moc”）。生成的文件放置在构建缓存中，而不是放置在可预测的项目路径中。对于需要在磁盘上使用 `.did` 文件的项目（例如，对于 `@icp-sdk/bindgen`），推荐的模式是：生成一次 `.did` 文件，提交它，并在配方配置中指定 `candid`。手动生成它： **Rust** — 首先构建 WASM，然后提取 Candid 接口：货物安装 candid-extractor # 一次性安装 ICP建设后台坦率提取器目标/wasm32-unknown-unknown/release/backend.wasm > backend/backend.did **Motoko** — 直接使用 `moc` 和 `--idl` 标志： $(mops 工具链 bin moc) --idl $(mops 源) -o backend/backend.did backend/app.mo ## 它是如何工作的 ### 项目创建 `icp new` 从模板构建项目。如果没有标志，则会启动交互式提示。对于脚本或非交互式使用，请直接传递 `--subfolder` 和 `--define` 标志。可用的模板和选项：[dfinity/icp-cli-templates]()。 ### 构建→部署→同步源代码 → [构建] → WASM → [部署] → 运行容器 → [同步] → 配置状态 `icp deploy` 按顺序运行所有三个阶段： 1. **构建** - 将容器编译为 WASM（通过配方或显式构建步骤） 2. **部署** — 创建容器（如果是新的）、应用设置、安装 WASM 3. **同步** — 部署后操作（例如，将资产上传到资产罐）单独运行阶段以获得更多控制： icp build # 仅构建 icp deploy # 完整管道（构建 + 部署 + 同步） icpsync my-canister # 仅同步（例如，重新上传资源） ### 环境和网络两个隐式环境始终可用：环境 |网络|目的 ---|---|--- `本地` | `local`（托管，本地主机：8000）|当地发展 `ic` | `ic`（已连接，）|主网制作 “ic”网络受到保护且无法被覆盖。自定义环境可在同一网络上启用多个部署目标：环境： - 名称：舞台网络：集成电路罐子：[前端，后端] 设置：后端：计算分配：5 - 名称：生产网络：集成电路罐子：[前端，后端] 设置：后端：计算分配：20 冻结阈值：7776000 ### 安装模式 icp deploy # 自动：安装新的，升级现有的（默认） icp部署--mode升级#保留状态，运行升级挂钩 icp deploy --mode reinstall # 清除所有状态（危险） ## 配置 ### 锈罐罐： - 名称：后端食谱：输入：“@dfinity/rust@v3.2.0” 配置：封装：后端 candid: backend.did # 可选 — 如果指定，文件必须存在（省略时自动生成） ### 元子罐罐： - 名称：后端食谱：输入：“@dfinity/motoko@v4.1.0” 配置：主要：src/backend/main.mo candid: backend.did # 可选 — 如果指定，文件必须存在（省略时自动生成） ### 资产罐（前端）罐： - 名称：前端食谱：输入：“@dfinity/asset-canister@v2.1.0” 配置：目录：区构建： - npm安装 - npm 运行构建对于多容器项目，请在同一“canisters”数组中列出所有容器。 icp-cli 并行构建它们。没有“依赖关系”字段 - 使用容器环境变量进行容器间通信。 ### 自定义构建步骤（无配方）不使用配方时，只有“name”、“build”、“sync”、“settings”和“init_args”是有效的容器级字段。没有“wasm”、“candid”或“metadata”字段——而是在构建脚本中处理这些字段： * **WASM 输出** ：将最终的 WASM 复制到 `$ICP_WASM_OUTPUT_PATH` * **Candid 元数据** ：使用 `ic-wasm` 嵌入 `candid:service` 元数据 * **Candid file** : `.did` 文件仅在 `ic-wasm` 命令中引用，而不是作为 YAML 字段引用罐： - 名称：后端构建：步骤： - 类型：脚本命令： - 货物构建--目标 wasm32-未知-未知--发布 - cp target/wasm32-unknown-unknown/release/backend.wasm“$ICP_WASM_OUTPUT_PATH” - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "$ICP_WASM_OUTPUT_PATH" 元数据 candid:service -f backend/backend.did -v public --keep-name-section ### 可用的食谱食谱|目的 ---|--- `@dfinity/rust` |带货物的锈罐 `@dfinity/motoko` |元子罐 `@dfinity/asset-canister` |静态文件的资产容器 `@dfinity/预建` |预编译的 WASM 文件使用 icp project show 查看配方扩展后的有效配置。 ### 容器环境变量 icp-cli 在“icp部署”期间自动注入所有容器 ID 作为环境变量。变量的格式为“PUBLIC_CANISTER_ID:”，并注入到环境中的每个容器中。 **前端 → 后端**（在 JavaScript 中读取容器 ID）：资产容器通过名为“ic_env”的 cookie 公开注入的变量，并在所有 HTML 响应上设置。使用`@icp-sdk/core`来读取它：从“@icp-sdk/core/agent/canister-env”导入{ safeGetCanisterEnv }； const canisterEnv = safeGetCanisterEnv(); const backendId = canisterEnv?.["PUBLIC_CANISTER_ID:backend"]; **后端 → 后端**（读取容器代码中的容器 ID）： * Rust: `ic_cdk::api::env_var_value("PUBLIC_CANISTER_ID:other_canister")` * Motoko（motoko-core v2.1.0+）：导入运行时“mo：核心/运行时”；让 otherId = Runtime.envVar("PUBLIC_CANISTER_ID:other_canister"); 注意：变量仅针对正在部署的容器进行更新。添加新容器时，运行“icp deploy”（不指定容器名称）以使用完整的 ID 集更新所有容器。 ### 绑定生成 icp-cli 没有内置的“dfxgenerate”命令。使用“@icp-sdk/bindgen”从“.did”文件生成 TypeScript 绑定。 **Vite插件**（推荐用于基于Vite的前端项目）： // vite.config.js 从“@icp-sdk/bindgen/plugins/vite”导入{ icpBindgen }；导出默认的defineConfig({ 插件：[ // 为前端需要访问的每个容器添加一个 icpBindgen() 调用 icpBindgen({ didFile: "../backend/backend.did", outDir: "./src/bindings/backend", }), icpBindgen({ didFile: "../other/other.did", outDir: "./src/bindings/other", }), ], }); 每个“icpBindgen()”实例在其“outDir”中生成一个“createActor”函数。将“**/src/bindings/”添加到“.gitignore”。 **从绑定创建 actor** — 将生成的绑定与 `ic_env` cookie 连接起来： // src/actor.js 从“@icp-sdk/core/agent/canister-env”导入{ safeGetCanisterEnv }；从“./bindings/backend”导入{createActor}； // 对于其他容器： import { createActor as createOther } from "./bindings/other"; const canisterEnv = safeGetCanisterEnv(); 常量代理选项 = { 主机：window.location.origin， rootKey: canisterEnv?.IC_ROOT_KEY, }; 导出常量后端 = createActor( canisterEnv?.["PUBLIC_CANISTER_ID:后端"], { 代理选项 } ）； // 对每个容器重复： createOther(canisterEnv?.["PUBLIC_CANISTER_ID:other"], { agentOptions }) **非 Vite 前端** — 使用 `@icp-sdk/bindgen` CLI 手动生成绑定： npx @icp-sdk/bindgen --did ../backend/backend.did --out ./src/bindings/backend **要求：** * `.did` 文件必须存在于磁盘上。如果使用指定了“candid”的配方，则必须提交该文件。如果省略了“candid”，请先运行“icp build”来自动生成它。 * `@icp-sdk/bindgen` 生成依赖于 `@icp-sdk/core` 的代码。使用“@dfinity/agent”的项目必须升级到“@icp-sdk/core”\+“@icp-sdk/bindgen”。这不是可选的 - 在停留在“@dfinity/agent”上时，无法使用 icp-cli 生成 TypeScript 绑定。 ### 开发服务器配置（Vite）在开发过程中，Vite 开发服务器必须模拟资产容器在生产中提供的“ic_env”cookie。查询本地网络的根密钥、容器 ID 和 API URL： // vite.config.js 从“child_process”导入{execSync}； const 环境 = process.env.ICP_ENVIRONMENT || “当地的”; // 列出前端需要访问的所有后端容器 const CANISTER_NAMES = ["后端", "其他"]; 函数 getCanisterId(名称) { // `-i` 使命令仅返回容器的标识 return execSync(`icp 容器状态 ${name} -e ${environment} -i`, { 编码：“utf-8”，stdio：“管道”， }).trim(); } 函数 getDevServerConfig() { const 网络状态 = JSON.parse( execSync(`icp 网络状态 -e ${环境} --json`, { 编码：“utf-8”， }) ）； const canisterParams = CANISTER_NAMES .map((名称) => `PUBLIC_CANISTER_ID:${name}=${getCanisterId(name)}`) .join("&"); 返回{ 标题：{ “设置 Cookie”：`ic_env=${encodeURIComponent( `${canisterParams}&ic_root_key=${networkStatus.root_key}` )}; SameSite=Lax;`, }, 代理：{ “/api”：{ target：networkStatus.api_url，changeOrigin：true }， }, }; } 与 dfx 的主要区别： * 代理目标和根密钥来自“icp network status --json”（无硬编码端口） * 容器 ID 来自“icp canister status -e -i”（无“.env”文件） * `ic_env` cookie 替换了 dfx 的 `CANISTER_ID_*` 环境变量 * `ICP_ENVIRONMENT` 让开发服务器可以针对任何环境（本地、staging、ic） ## dfx → icp 迁移 ### 本地网络端口更改 dfx 在端口“4943”上为本地网络提供服务。 icp-cli 使用端口“8000”。迁移时，在项目中搜索对“4943”（或“localhost:4943”）的硬编码引用，并将其更新为“8000”。更好的是，使用“icp network status --json”动态获取“api_url”（请参阅上面的开发服务器配置）。常见的检查地点： * Vite/webpack 代理配置（例如 `vite.config.ts`） * 自述文件 * 测试装置和脚本 ### 删除`.env`文件和`output_env_file` dfx 通过“dfx.json”中的“output_env_file”生成带有“CANISTER_ID_*”变量的“.env”文件。 icp-cli 不使用“.env”文件作为容器 ID - 从配置中删除“output_env_file”并删除任何 dfx 生成的“.env”文件。还要从“.env”文件中删除特定于 dfx 的环境变量（例如“DFX_NETWORK”、“NETWORK”）。将读取“process.env.CANISTER_ID_*”的代码替换为“ic_env”cookie 模式（请参阅上面的容器环境变量）。 ### 前端包迁移由于“@icp-sdk/bindgen”生成依赖于“@icp-sdk/core”的代码，因此具有 TypeScript 绑定的项目**必须**从“@dfinity/*”包升级。这不是可选的 - icp-cli 中不存在“dfxgenerate”，并且“@icp-sdk/bindgen”是唯一支持的生成绑定的方式。删除|替换为 ---|--- `@dfinity/agent` | `@icp-sdk/core` `@dfinity/坦率` | `@icp-sdk/core` `@dfinity/principal` | `@icp-sdk/core` `dfx 生成`（声明）| `@icp-sdk/bindgen` （Vite 插件或 CLI） `vite-插件环境` |不需要 — 使用 `ic_env` cookie `src/declarations/` （由 dfx 生成）| `src/bindings/` （由 `@icp-sdk/bindgen` 生成）步骤： 1. `npm uninstall @dfinity/agent @dfinity/candid @dfinity/principal vite-plugin-environment` 2. `npm install @icp-sdk/core @icp-sdk/bindgen` 3.删除`src/declarations/`（dfx生成的绑定） 4. 将 `**/src/bindings/` 添加到 `.gitignore` 5. 提交bindgen使用的`.did`文件 6. 将 `icpBindgen()` 添加到 `vite.config.js` （参见上面的绑定生成） 7. 替换 actor 设置代码：使用生成的绑定中的 `@icp-sdk/core` \+ `createActor` 中的 `safeGetCanisterEnv`（请参阅上面的从绑定创建 actor） 8. 删除 `process.env.CANISTER_ID_*` 引用 — 使用 `ic_env` cookie 代替 ### 命令映射任务| dfx | ICP ---|---|--- 创建项目| `dfx 新 my_project` | `icp 新 my_project` 启动本地网络 | `dfx 开始 --background` | `icp 网络启动 -d` 停止本地网络 | `dfx 停止` | `icp网络停止` 构建 | `dfx 构建` | `icp 构建` 部署全部 | `dfx 部署` | `icp部署` 部署到主网 | `dfx 部署 --network ic` | `icp部署-e ic` 呼叫罐| `dfx 容器调用 X 方法 '(args)'` | `icp 容器调用 X 方法 '(args)'` 获取容器 ID | `dfx 容器 ID X` | `icp 容器状态 X --id-only` 罐状态 | `dfx 容器状态 X` | `icp 容器状态 X` 列出罐 | `dfx 罐 ls` | `icp 容器列表` 创建身份 | `dfx 身份新 my_id` | `icp身份新my_id` 设置默认身份 | `dfx 身份使用 my_id` | `icp身份默认my_id` 显示校长 | `dfx 身份获取主体` | `icp 身份主体` 出口身份| `dfx 身份导出 my_id` | `icp身份导出my_id` 删除身份 | `dfx 身份删除 my_id` | `icp身份删除my_id` 获取账户ID | `dfx 分类账账户 ID` | `icp 身份帐户 ID` 检查 ICP 余额 | `dfx 分类帐余额` | `icp代币余额` 检查周期| `dfx 钱包余额` | `icp 周期平衡` ### 配置映射 dfx.json | icp.yaml ---|--- `“类型”：“铁锈”` | `配方.类型：“@dfinity/rust@v3.2.0”` `"type": "motoko"` | `配方.类型：“@dfinity/motoko@v4.1.0”` `“类型”：“资产”` | `recipe.type: "@dfinity/asset-canister@v2.1.0"` `“包”：“X”` | `recipe.configuration.package: X` `“坦率”：“X”` | `recipe.configuration.candid: X` `“主”：“X”` | `recipe.configuration.main: X` `“来源”：[“距离”]` | `recipe.configuration.dir: dist` `“依赖项”：[...]` |不需要 — 使用 Canister 环境变量 `"output_env_file": ".env"` |不需要 — 使用 `ic_env` cookie `dfx 生成` | `@icp-sdk/bindgen` Vite 插件 `--网络IC` | `-e ic` ### 身份迁移 # 从 dfx 导出，导入到 icp-cli dfx 身份导出 my-identity > /tmp/my-identity.pem icp 身份导入 my-identity --from-pem /tmp/my-identity.pem rm /tmp/my-identity.pem # 验证主体是否匹配 dfx 身份 get-principal --identity my-identity icp 身份主体 --identity my-identity ### 容器 ID 迁移如果您有由 dfx 管理的现有主网容器，请将 ID 从“canister_ids.json”迁移到 icp-cli 的映射文件： # 从 dfx 获取 ID dfx 容器 ID 前端 --network ic dfx 容器 ID 后端 --network ic # 为 icp-cli 创建映射文件 mkdir -p .icp/数据/映射猫 > .icp/data/mappings/ic.ids.json << 'EOF' { “前端”：“xxxxx-xxxxx-xxxxx-xxxxx-cai”， “后端”：“yyyyy-yyyyy-yyyyy-yyyyy-cai” } EOF # 删除 dfx 容器 ID 文件 — icp-cli 使用 .icp/data/mappings/ 代替 rm -f canister_ids.json # 致力于版本控制 git add .icp/数据/ ## 迁移后验证将项目从 dfx 迁移到 icp-cli 后，请验证以下内容： 1. **已删除的文件**：`dfx.json` 和 `canister_ids.json` 不再存在 2. **创建的文件** : `icp.yaml` 存在。 `.icp/data/mappings/ic.ids.json` 存在并已提交（如果项目有主网容器） 3. **`.gitignore`** ：包含`.icp/cache/`，不包含`.dfx` 4. **没有过时的端口引用**：在代码库中搜索 `4943` — 应该有零个匹配项 5. **无 dfx env 模式**：搜索 `output_env_file`、`CANISTER_ID_`、`DFX_NETWORK` — 配置文件和源文件中应该有零个匹配项 6. **前端包**（如果项目具有 TypeScript 绑定）：`@dfinity/agent` 不在 `package.json` 中，`@icp-sdk/core` 和 `@icp-sdk/bindgen` 中。 `src/declarations/` 被删除，`src/bindings/` 位于 `.gitignore` 中 7. **Candid 文件** : 提交 `@icp-sdk/bindgen` 使用的 `.did` 文件 8. **构建成功** : `icp build` 完成且没有错误 9. **配置正确** : `icp project show` 显示预期的扩展配置 10. **自述文件**：引用`icp`命令（不是`dfx`），说“本地网络”（不是“副本”），显示正确的端口

Icp客户端

包含技能