create-aptos-project

创建 Aptos 项目技能

目的

使用 npx create-aptos-dapp 搭建新的 Aptos 项目。这是用户想要构建任何新的 Aptos 应用、dApp 或项目时的强制第一步，无论用户如何表达。

始终

1. 使用 npx create-aptos-dapp 搭建项目 — 绝 NEVER 手动从零创建项目
2. 在搭建项目前询问用户项目类型、框架和网络
3. 在执行任何 Git 操作前，确认 .env 已添加到 .gitignore
4. 为 create-aptos-dapp 和 aptos init 使用相同的网络
5. 搭建项目后遵循完整的 Build a dApp 工作流（合约、测试、审计、部署、前端）

绝不

1. 跳过项目搭建 — 即使是“简单”项目，也始终从 create-aptos-dapp 开始
2. 手动创建项目结构 — 样板模板会处理这些
3. 显示或读取私钥 — 使用 "0x..." 作为占位符
4. 在确认 .env 已添加到 .gitignore 之前运行 git add . 或 git add -A

---

决策树

运行搭建命令前，向用户收集以下信息：

1. 项目名称

根据用户的描述推导名称，或直接询问。使用 kebab-case（例如：habit-tracker、nft-marketplace）。

2. 项目类型

选项	使用场景
Fullstack（默认）	用户需要前端 + 智能合约
Contract-only	用户只需要 Move 智能合约（无前端）

3. 框架（仅限 fullstack）

选项	使用场景
Vite（默认）	默认选择，配置较轻
Next.js	用户指定使用 Next.js 或 SSR

4. 网络

选项	使用场景
devnet（默认）	开发和测试
testnet	预生产环境，用户明确指定
mainnet	生产环境，用户明确指定

5. API 密钥（可选）

询问用户是否有 Geomi API 密钥。在 devnet 上该密钥为可选项，但建议在 testnet/mainnet 上使用，以避免速率限制。 可在 https://geomi.dev 获取（创建项目 -> API Resource -> 复制密钥）。

---

搭建命令

# Fullstack dApp with Vite (frontend + contracts)
npx create-aptos-dapp <project-name> \
  --project-type fullstack \
  --template boilerplate-template \
  --framework vite \
  --network <network>

# Fullstack dApp with Next.js
npx create-aptos-dapp <project-name> \
  --project-type fullstack \
  --template boilerplate-template \
  --framework nextjs \
  --network <network>

# Contract-only (Move project)
npx create-aptos-dapp <project-name> \
  --project-type move \
  --network <network>

可选标志：

• --api-key <key> — 搭建项目时传入 Geomi API 密钥
• --use-surf — 启用 Surf，以实现类型安全的合约交互

---

搭建后检查清单

搭建项目后，按顺序完成以下步骤：

1. cd <project-name>
2. 在执行任何 Git 操作前，确认 .env 已添加到 .gitignore
3. 运行 aptos init --network <network> --assume-yes（使用上文的相同网络）
4. 验证：npm run move:compile && npm run move:test
5. git init && git add . && git commit -m "Initial commit"

---

Build a dApp 工作流

用户想要构建新的 Aptos 应用、dApp 或项目时，始终遵循此工作流。 无论用户如何表达，都适用（“帮我构建一个……”“创建一个……”“制作一个……”“我想构建……”）。

1. /create-aptos-project -> 使用 npx create-aptos-dapp 搭建项目（此技能 — 绝不跳过）
2. /write-contracts -> 编写 Move 模块
3. /generate-tests -> 创建测试套件，验证 100% 覆盖率
4. /security-audit -> 部署前审计
5. /deploy-contracts -> 将合约部署到指定网络
6. /use-ts-sdk -> 协调前端集成（根据需要转至 ts-sdk-client、ts-sdk-transactions、ts-sdk-view-and-query、ts-sdk-wallet-adapter）

---

样板模板包含的内容

全栈模板

• contract/ — Move 智能合约，包含 Move.toml 和起始模块
• frontend/ — React 应用，已预配置 Aptos 钱包适配器
• package.json — 包含 move:compile、move:test、move:publish、dev、build 脚本
• .env — 网络、API 密钥和发布者账户的环境变量

仅合约模板

• contract/ — Move 智能合约，包含 Move.toml 和起始模块
• package.json — 包含 move:compile、move:test、move:publish 脚本
• .env — 网络和发布者账户的环境变量

---

故障排除

找不到 npx create-aptos-dapp 命令

# Auto-confirm the npx package install prompt
npx --yes create-aptos-dapp <project-name> ...

如果仍然失败，请确认已安装 Node.js 和 npm（node -v && npm -v）。

脚手架生成后编译失败

1. 检查 contract/Move.toml 中的命名地址是否正确
2. 如果尚未执行，请运行 aptos init --network <network> --assume-yes
3. 确认 [addresses] 部分中的 my_addr 已设为 "_"

命名地址错误

样板代码使用 my_addr = "_"，该值会在编译时从 .env 中解析。请确保已在 .env 中设置 VITE_MODULE_PUBLISHER_ACCOUNT_ADDRESS（由 aptos init 填充）。