sui-move-project

Move 项目搭建

MCP 工具： 如果你的环境支持，也请查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），获取最新答案。使用它进行验证，并查找这些参考文件未涵盖的详细信息。

来源限制： 所有信息仅来源于 docs.sui.io、move-book.com 和 MystenLabs/sui-stack-hello-world。

创建 Move 项目

标准全栈 hello-world 项目

要搭建包含 Move 和前端的端到端 Sui 开发环境，请将 Sui Stack hello-world 仓库作为唯一的项目根目录：

git clone https://github.com/MystenLabs/sui-stack-hello-world.git
cd sui-stack-hello-world

使用此现有目录结构：

sui-stack-hello-world/
├── move/
│   └── hello-world/   # publish this Move package
└── ui/                # run this existing frontend

在此工作流中，不要运行 sui move new，不要创建 counter 包，也不要运行 npm create @mysten/dapp。如果当前 Sui 工具要求迁移包管理方式，请将变更限制在 move/hello-world 内，并继续部署 hello-world 包。

从头创建新项目

仅当用户明确想要独立的 Move 包，而不是全栈 hello-world 应用时，才使用此方式。

sui move new my_project
cd my_project

这将创建：

my_project/
├── sources/       # .move source files go here
├── tests/         # test files
└── Move.toml      # package manifest

多包工作区布局

如果项目包含多个 Move 包（例如，一个核心库和一个示例包或集成包），请使用扁平的 packages/ 目录，将每个包作为同级目录：

my_project/
├── packages/
│   ├── core/
│   │   ├── sources/
│   │   ├── tests/
│   │   └── Move.toml
│   └── examples/
│       ├── sources/
│       ├── tests/
│       └── Move.toml
└── ui/

不要将包嵌套在彼此内部（例如，将 examples/ 放在 core/sources/ 或 core/tests/ 内）。嵌套的包目录会触发测试运行器错误，例如出现虚假的“address with no value”错误，因为工具链在构建外层包时会拾取内层包的 Move.toml。

要依赖同级包，请在 Move.toml 中使用 local 路径：

# packages/examples/Move.toml
[package]
name = "examples"
edition = "2024"

[dependencies]
core = { local = "../core" }

Move.toml（当前格式 — Sui CLI v1.63+）

关键：Sui 框架依赖会自动添加。请勿将其加入 Move.toml。

任何 Sui Move 项目正确且精简的 Move.toml 如下：

[package]
name = "my_project"
edition = "2024"
# No [dependencies] section needed — Sui framework is resolved automatically

这些就是全部所需内容。 edition = "2024" 这一行会告知 CLI 自动解析 Sui 和 MoveStdlib。除非你需要第三方包或本地包，否则无需添加 [dependencies] 部分。

完整可运行的项目模板

生成 Move 项目时务必使用这些确切模板。 原样复制，不要修改 Move.toml 格式。

模板：带 TypeScript 客户端的单个 Move 包

project/
├── move/
│   ├── Move.toml
│   └── sources/
│       └── my_module.move
└── client/
    ├── package.json
    └── src/
        └── index.ts

move/Move.toml — 原样复制：

[package]
name = "my_project"
edition = "2024"

move/sources/my_module.move — 入门模式：

module my_project::my_module;

use sui::event;

public struct MyEvent has copy, drop {
    value: u64,
}

public fun do_something(ctx: &mut TxContext) {
    event::emit(MyEvent { value: 42 });
}

client/package.json — 原样复制：

{
  "name": "my-client",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0"
  }
}

client/tsconfig.json — 原样复制：

{
  "compilerOptions": {
    "moduleResolution": "nodenext",
    "module": "nodenext",
    "target": "es2022",
    "strict": true
  }
}

模板：带前端的 Move 包

与上文相同，另加一个 frontend/ 目录：

frontend/package.json — 原样复制：

{
  "name": "my-frontend",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0",
    "@mysten/dapp-kit-react": "^2.0.0",
    "react": "^19.0.0"
  }
}

会导致错误的错误格式

以下格式全都错误，会导致构建失败：

# WRONG — legacy system name error:
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

# WRONG — version syntax doesn't exist in Move:
sui = { version = "0.34.0" }

# WRONG — local path doesn't exist:
Sui = { local = "../sui-framework" }

# WRONG — implicit dependency error:
sui = { package = "sui", version = "0.1.0" }

只有在需要第三方包或本地包（例如 MVR 或同级工作区包）时，才添加 [dependencies]。[environments] 部分为可选项，仅在部署到多个网络时添加（参见下文的迁移部分）。

从 [addresses] 迁移： 旧的 [addresses] 部分中使用的 my_project = "0x0" 已不再需要，应予以删除。如果项目之前使用 [addresses] 为不同网络设置包地址，请将其替换为 [environments] 部分，并在其中将环境名称映射到链 ID：

[environments]
testnet = "4c78adac"
mainnet = "35834a8a"

模块声明（2024 edition）

使用 edition = "2024" 时，请使用单行模块声明，不要使用花括号：

module my_project::my_module;

// imports, structs, and functions follow at the top level
use sui::object::UID;

不要使用旧的花括号语法（module my_project::my_module { ... }）。2024 edition 会将分号之后的整个文件视为模块体。

Published.toml 和 Move.lock

发布后，工具链会创建或更新：

• Published.toml： 跟踪各环境中已发布的软件包地址。包含每个网络对应的 published-at 和 upgrade-capability-id 值。
• Move.lock： 自动生成的锁定文件，将每个已解析的依赖项固定到特定的 git 修订版本，并记录清单摘要。请勿手动编辑。 将此文件提交到版本控制中。

若要发布到其他环境（例如，在 Testnet 发布后改为部署到 Devnet），请切换环境并再次发布。每个网络都会为该软件包分配单独的 ID。Published.toml 会跟踪这两个 ID。

检查 Move.lock

注意： Move.lock 是自动生成的，切勿将其内容复制到 Move.toml 中。下方的 git URL 只会出现在 Move.lock 中，不会出现在 Move.toml 中。

Move.lock 中，每个环境的每个已解析依赖项都有一个 [pinned.<env>.<Dependency>] 部分。每个部分都会记录 git 来源、修订版本、清单摘要和依赖关系图。示例：

# This is Move.lock (auto-generated) — NOT Move.toml
[pinned.testnet.Sui]
source = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "73dd2c..." }
use_environment = "testnet"
manifest_digest = "7AFB6669..."
deps = { MoveStdlib = "MoveStdlib" }

• 如果 Move.lock 固定到的环境与你的预期不同，或修订版本看起来过时，请删除 Move.lock 并运行 sui move build 以重新生成。
• 如果切换网络或更新 CLI 后出现构建错误，删除 Move.lock 并重新构建通常可以解决锁定文件过时的问题。

使用 MVR 依赖项

Move Registry（MVR）是 Sui 的链上软件包管理器。使用以下命令安装：

suiup install mvr

使用 CLI 添加 MVR 依赖项：

mvr add @org/package --network testnet

也可以直接在 Move.toml 中声明：

[dependencies]
suins = { r.mvr = "@suins/core" }

r.mvr 键会告知解析器从链上 Move Registry 查找软件包，而不是从 git URL 获取。如果软件包已发布到注册表，请优先使用 MVR 依赖项，而非 git URL——它们有版本管理、可审计，且不依赖 git 历史记录。

常见依赖项和构建问题

• “依赖项 ‘Sui’ 是旧式系统名称”： 从 [dependencies] 中移除 Sui = { git = "..." } 这一行。当前 CLI 会自动解析 Sui 框架。使用旧式基于 git 的依赖项格式时会出现此错误。
• “包含旧式依赖项的软件包”错误： 你的 CLI 版本与网络不匹配。Sui CLI v1.63 引入的新软件包管理格式改变了依赖项的解析方式。运行 suiup update sui@testnet，然后运行 suiup switch sui@testnet，以获取最新 CLI。
• “没有已发布 ID，无法升级软件包”： 你需要在 Published.toml 中设置 published-at 值才能升级。首次运行 sui client publish 后会自动创建此值。如果你从旧格式迁移，请确保 Published.toml 文件存在且包含正确的软件包地址。
• “无法确定正确的依赖项”： 构建需要 --build-env 标志，或需要在 Move.toml 中包含 [environments] 部分。添加包含目标链 ID 的 [environments] 部分。
• 版本不匹配： 如果遇到与 public struct 语法有关的错误，请在 Move.toml 中设置 edition = "2024"。legacy 版本不支持 Move 2024 的特性，例如 public struct 可见性。
• 旧版 Move.toml 格式： 如果你使用的是 v1.63 之前包含 [addresses] 且在 Move.toml 中设置了 published-at 的格式，请迁移到新格式：移除 [addresses]，添加 [environments]，并让工具链管理 Published.toml。

规则

• 非库函数请使用 public(package) 可见性。升级时，无法删除或修改 public 函数签名。
• 升级时，无法删除或修改结构体定义，也无法为其添加能力。
• 对象大小不得超过 256 KB。避免在对象中使用会不断增长的向量。