deploy-contracts

部署合约技能

概述

此技能指导你如何安全地将 Move 合约部署到 Aptos 网络。始终先部署到测试网，再部署到主网。

部署前检查清单

部署前，请确认以下所有事项：

安全审计 ⭐ 严重 - 参见 SECURITY.md

• 已完成安全审计（使用 security-audit 技能）
• 已修复所有严重漏洞
• 已验证所有安全模式（算术安全、存储范围限定、引用安全、业务逻辑）
• 已验证访问控制（签名者检查、对象所有权）
• 已实现输入验证（最低阈值、费用验证）
• 没有无界迭代（使用每位用户的存储，而非全局向量）
• 操作具有原子性（不存在抢先交易的机会）
• 随机数安全（如适用：入口函数、Gas 均衡）

测试

• 已达到 100% 测试覆盖率：aptos move test --coverage
• 所有测试均已通过：aptos move test
• 覆盖率报告显示 100.0%
• 已测试边界情况

代码质量

• 代码编译无错误：aptos move compile
• 没有硬编码地址（使用命名地址）
• 已明确定义错误代码
• 已妥善记录函数文档

配置

• Move.toml 配置正确
• 已设置命名地址：my_addr = "_"
• 已指定正确版本的依赖项
• 已配置网络 URL

对象部署（现代模式）

严重：使用正确的部署命令

部署合约有两种方式。对于现代对象型合约，请使用 deploy-object：

✅ 正确：对象部署（现代模式）

aptos move deploy-object \
    --address-name my_addr \
    --profile devnet \
    --assume-yes

此命令的作用：

1. 创建一个用于托管合约代码的对象
2. 将包部署到该对象的地址
3. 返回对象地址（基于部署者和包名称确定性生成）
4. 对象地址成为你的合约地址

❌ 错误：对对象型合约使用常规发布

# ❌ Don't use this for object-based contracts
aptos move publish \
    --named-addresses my_addr=<address>

何时使用哪种方式：

• deploy-object：使用对象的现代合约（推荐）
• publish：基于账户的旧式部署（较早的模式）

如何判断是否需要对象部署：

• 你的合约在 init_module 中创建命名对象
• 你的合约使用 object::create_named_object()
• 你希望合约地址具有确定性
• 文档说明“作为对象部署”

其他对象部署命令

选项 1：deploy-object（推荐——最简单）

aptos move deploy-object --address-name my_addr --profile devnet

• 自动创建对象并部署代码
• 对象地址具有确定性
• 适用于大多数使用场景

选项 2：create-object-and-publish-package（高级）

aptos move create-object-and-publish-package \
    --address-name my_addr \
    --named-addresses my_addr=default

• 命令更复杂，选项更多
• 仅在需要特定对象配置时使用
• 通常不需要

**建议：**除非有特定理由使用其他方式，否则始终使用 deploy-object。

部署工作流

第 1 步：本地测试

# Ensure all tests pass
aptos move test

# Verify 100% coverage
aptos move test --coverage
aptos move coverage summary
# Expected output: "coverage: 100.0%"

第 2 步：编译

# Compile contract
aptos move compile --named-addresses my_addr=<your_address>

# Verify compilation succeeds
echo $?
# Expected: 0 (success)

第 3 步：部署到开发网（可选）

开发网适用于快速测试和实验。运行 aptos init 时，账户会自动获得资金。

初始化前，请检查配置文件是否存在：

# Check if default profile exists (look for "default" in output)
aptos config show-profiles

# If no profile exists, initialize one (auto-funds on devnet)
aptos init --network devnet --assume-yes

# Deploy as object (modern pattern)
aptos move deploy-object \
    --address-name my_addr \
    --profile default \
    --assume-yes

# Save the object address from output for future upgrades
# Output: "Code was successfully deployed to object address 0x..."

# Verify deployment
aptos account list --account <object_address> --profile default

第 4 步：部署到测试网（必需）

测试网用于在主网部署前进行最终测试。

初始化前，请检查配置文件是否存在：

# Check if default profile exists
aptos config show-profiles

# If no profile exists, initialize one
aptos init --network testnet --assume-yes

通过网页水龙头为账户充值（必需——测试网水龙头需要 Google 登录）：

1. 获取你的账户地址：aptos config show-profiles
2. 前往：https://aptos.dev/network/faucet?address=<your_address>
3. 登录并申请测试网 APT
4. 返回此处并确认已为账户充值

# Verify balance
aptos account balance --profile default

# Deploy to testnet as object (modern pattern)
aptos move deploy-object \
    --address-name my_addr \
    --profile default \
    --assume-yes

# IMPORTANT: Save the object address from output
# You'll need it for upgrades and function calls
# Output: "Code was successfully deployed to object address 0x..."

第 5 步：在测试网上测试

# Run entry functions to verify deployment
aptos move run \
    --profile default \
    --function-id <deployed_address>::<module>::<function> \
    --args ...

# Test multiple scenarios
# - Happy paths
# - Error cases (should abort with correct error codes)
# - Access control
# - Edge cases

# Verify using explorer
# https://explorer.aptoslabs.com/?network=testnet

第 6 步：部署到主网（测试网测试成功后）

只有在测试网上完成充分测试后，才能部署到主网。

初始化前，请检查配置文件是否存在：

# Check if default profile exists
aptos config show-profiles

# If no profile exists, initialize one
# IMPORTANT: Warn user that this generates a private key — store it securely
aptos init --network mainnet --assume-yes

**为账户充值：**从交易所或钱包向你的账户地址转入真实 APT。

# Verify balance
aptos account balance --profile default

# Deploy to mainnet as object (modern pattern)
aptos move deploy-object \
    --address-name my_addr \
    --profile default \
    --max-gas 20000  # Optional: set gas limit

# Review prompts carefully before confirming:
# 1. Gas confirmation: Review gas costs
# 2. Object address: Note the object address for future reference

# OR use --assume-yes to auto-confirm (only if you're confident)
aptos move deploy-object \
    --address-name my_addr \
    --profile default \
    --assume-yes

# SAVE THE OBJECT ADDRESS from output
# You'll need it for upgrades and documentation

# Confirm deployment
# Review transaction in explorer:
# https://explorer.aptoslabs.com/?network=mainnet

第 7 步：验证部署

# Check module is published
aptos account list --account <deployed_address> --profile default

# Look for your module in the output
# "0x...::my_module": { ... }

# Run view function to verify
aptos move view \
    --profile default \
    --function-id <deployed_address>::<module>::<view_function> \
    --args ...

第 8 步：记录部署

创建部署记录：

# Deployment Record

**Date:** 2026-01-23 **Network:** Mainnet **Module:** my_module **Address:** 0x123abc... **Transaction:** 0x456def...

## Verification

- [x] Deployed successfully
- [x] Module visible in explorer
- [x] View functions working
- [x] Entry functions tested

## Links

- Explorer: https://explorer.aptoslabs.com/account/0x123abc...?network=mainnet
- Transaction: https://explorer.aptoslabs.com/txn/0x456def...?network=mainnet

## Notes

- All security checks passed
- 100% test coverage verified
- Tested on testnet for 1 week before mainnet

模块升级

升级现有对象部署

默认情况下，部署者可以升级对象部署的模块。

# Upgrade existing object deployment
aptos move upgrade-object \
    --address-name my_addr \
    --object-address <object_address_from_initial_deploy> \
    --profile mainnet

# Upgrade with auto-confirm
aptos move upgrade-object \
    --address-name my_addr \
    --object-address <object_address> \
    --profile mainnet \
    --assume-yes

# Verify upgrade
aptos account list --account <object_address> --profile mainnet

**重要：**保存首次 deploy-object 输出中的对象地址——升级时需要用到它。

升级兼容性规则：

• ✅ **可以：**添加新函数
• ✅ **可以：**添加新结构体
• ✅ **可以：**向结构体添加新字段（需谨慎）
• ❌ **不可以：**移除现有函数（会破坏兼容性）
• ❌ **不可以：**更改函数签名（会破坏兼容性）
• ❌ **不可以：**移除结构体字段（会破坏现有数据）

将模块设为不可变

要阻止未来的升级：

// In your module
fun init_module(account: &signer) {
    // After deployment, burn upgrade capability
    // (implementation depends on your setup)
}

成本估算

Gas 成本

# Typical deployment costs:
# - Small module: ~500-1000 gas units
# - Medium module: ~1000-5000 gas units
# - Large module: ~5000-20000 gas units

# When you run deploy-object, the CLI shows gas estimate before confirming
# Use --assume-yes only after you've verified costs on testnet first

主网成本

Gas 费用以 APT 支付：

• Gas 单位数 × Gas 价格 = 总成本
• 示例：5000 个 Gas 单位 × 100 Octas/Gas = 500,000 Octas = 0.005 APT

多模块部署

部署多个模块

选项 1：单个包（推荐）

project/
├── Move.toml
└── sources/
    ├── module1.move
    ├── module2.move
    └── module3.move

# Deploys all modules at once as a single object
aptos move deploy-object --address-name my_addr --profile testnet

选项 2：使用依赖项的独立包

# Deploy dependency package first
cd dependency-package
aptos move deploy-object --address-name dep_addr --profile testnet
# Note the object address from output

# Update main package Move.toml to reference dependency address
# Then deploy main package
cd ../main-package
aptos move deploy-object --address-name main_addr --profile testnet

部署故障排除

“APT 余额不足”

**Devnet：**运行 aptos init 时会自动注资。如有需要，请运行：

aptos account fund-with-faucet --account default --amount 100000000 --profile default

**Testnet：**使用网页水龙头（需要 Google 登录）：

1. 获取账户地址：aptos config show-profiles
2. 访问：https://aptos.dev/network/faucet?address=<your_address>
3. 登录并申请 Testnet APT
4. 验证余额：aptos account balance --profile default

**Mainnet：**从交易所或钱包向账户转入真实 APT。

“模块已存在”（用于对象部署）

# Use upgrade-object with the original object address
aptos move upgrade-object \
    --address-name my_addr \
    --object-address <object_address_from_initial_deploy> \
    --profile testnet

“编译失败”

# Fix compilation errors first
aptos move compile
# Fix all errors shown, then retry deployment

“超出 Gas 限制”

# Increase max gas
aptos move deploy-object \
    --address-name my_addr \
    --profile testnet \
    --max-gas 50000

部署检查清单

部署前：

• 安全审计已通过
• 测试覆盖率达到 100%
• 所有测试均已通过
• 代码编译成功
• 已配置命名地址
• 已选择目标网络（先选 Testnet！）

部署期间：

• 已选择正确的网络
• 已指定正确的地址
• 已提交交易
• 已记录交易哈希

部署后：

• 在浏览器中可以看到模块
• 视图函数可正常运行
• 入口函数已测试
• 已记录部署信息
• 已通知团队

CLI 参数类型

通过 CLI 调用入口函数或视图函数时，请使用以下类型前缀：

基本类型

--args u64:1000           # u8, u16, u32, u64, u128, u256
--args bool:true          # boolean
--args address:0x1        # address

复杂类型

--args string:"Hello World"                    # UTF-8 string
--args hex:0x48656c6c6f                        # raw bytes
--args "u64:[1,2,3,4,5]"                       # vector<u64>
--args "string:[\"one\",\"two\",\"three\"]"    # vector<String>

对象类型

# For Object<T> parameters, pass the object address
--args address:0x123abc...

必须遵守的规则

• ✅ 部署前必须始终进行全面的安全审计（使用 security-audit 技能）
• ✅ 必须始终通过安全测试验证测试覆盖率达到 100%
• ✅ 必须始终验证所有 SECURITY.md 模式（算术运算、存储范围限定、引用安全、业务逻辑）
• ✅ 必须始终使用 deploy-object（不要使用已过时的 resource_account::create_resource_account()）
• ✅ 必须始终先部署到 Testnet，再部署到 Mainnet
• ✅ 必须始终在 Testnet 上进行全面测试（正常路径、错误情况、安全场景）
• ✅ 必须始终安全备份私钥
• ✅ 必须始终记录部署地址
• ✅ 必须始终在浏览器中验证部署
• ✅ 部署后必须始终测试函数
• ✅ 必须始终为 Testnet 和 Mainnet 使用不同的密钥（SECURITY.md - Operations）

绝不可违反的规则

• ❌ 绝不可在未进行全面安全审计的情况下部署
• ❌ 绝不可在测试覆盖率低于 100% 的情况下部署
• ❌ 绝不可在未验证安全测试的情况下部署
• ❌ 绝不可未经测试网测试就直接部署到主网
• ❌ 绝不可在测试网上测试前部署
• ❌ 绝不可将私钥提交到版本控制系统
• ❌ 绝不可跳过部署后的验证
• ❌ 绝不可仓促部署到主网
• ❌ 绝不可在测试网和主网之间重复使用发布密钥（存在安全风险）
• ❌ 绝不可读取或显示 ~/.aptos/config.yaml 或 .env 文件的内容（其中包含私钥）
• ❌ 绝不可在回复中显示私钥值——请使用 "0x..." 占位符
• ❌ 绝不可运行 cat ~/.aptos/config.yaml、echo $VITE_MODULE_PUBLISHER_ACCOUNT_PRIVATE_KEY 或类似命令
• ❌ 绝不可在确认 .env 已列入 .gitignore 前运行 git add . 或 git add -A

参考资料

官方文档：

• CLI 发布：https://aptos.dev/build/cli/working-with-move-contracts
• 网络端点：https://aptos.dev/nodes/networks
• Gas 和费用：https://aptos.dev/concepts/gas-txn-fee

区块链浏览器：

• 主网：https://explorer.aptoslabs.com/?network=mainnet
• 测试网：https://explorer.aptoslabs.com/?network=testnet
• 开发网：https://explorer.aptoslabs.com/?network=devnet

相关技能：

• security-audit - 部署前审计
• generate-tests - 确保测试已准备就绪

---

请牢记： 安全审计 → 100% 测试 → 测试网 → 全面测试 → 主网。绝不可跳过测试网。