sui-move-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Move Project Setup

Move 项目搭建

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Source constraint: All information sourced exclusively from docs.sui.io, move-book.com, and MystenLabs/sui-stack-hello-world.

MCP 工具： 当你的环境中可用时，也可查询Sui文档MCP服务器（
https://sui.mcp.kapa.ai
）获取最新答案。用它来验证信息，以及获取这些参考文件未涵盖的细节。

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

Creating a Move project

创建Move项目

Canonical full-stack hello-world project

标准全栈hello-world项目

For an end-to-end Sui developer environment with Move and frontend, use the Sui Stack hello-world repository as the single project root:

bash

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

Use this existing layout:

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

Do not run

sui move new

, do not create a counter package, and do not run

npm create @mysten/dapp

for this workflow. If current Sui tooling requires a package-management migration, keep the change inside

move/hello-world

and continue deploying the hello-world package.

如需包含Move和前端的端到端Sui开发者环境，可将Sui Stack hello-world仓库作为单一项目根目录：

bash

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

使用现有布局：

sui-stack-hello-world/
├── move/
│   └── hello-world/   # 发布此Move包
└── ui/                # 运行现有前端

在此工作流中，请勿运行

sui move new

、创建counter包或运行

npm create @mysten/dapp

。如果当前Sui工具需要进行包管理迁移，请将修改限制在

move/hello-world

内，并继续部署hello-world包。

New project from scratch

从零开始创建新项目

Use this only when the user explicitly wants a standalone Move package rather than the full-stack hello-world app.

bash

sui move new my_project
cd my_project

This creates:

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

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

bash

sui move new my_project
cd my_project

此命令会创建：

my_project/
├── sources/       # .move源文件存放于此
├── tests/         # 测试文件
└── Move.toml      # 包清单

Multi-package workspace layout

多包工作区布局

When a project contains more than one Move package (for example, a core library and an example or integration package), use a flat

packages/

directory with each package as a sibling:

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

Do not nest packages inside each other (for example, placing

examples/

inside

core/sources/

core/tests/

). Nested package directories trigger test runner bugs such as spurious "address with no value" errors because the toolchain picks up the inner package's

Move.toml

when building the outer one.

To depend on a sibling package, use a

local

path in

Move.toml

toml

undefined

当项目包含多个Move包时（例如核心库和示例/集成包），使用扁平的

packages/

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

请勿嵌套包目录（例如将

examples/

放在

core/sources/

或

core/tests/

内）。嵌套包目录会触发测试运行器bug，比如出现虚假的“address with no value”错误，因为工具链在构建外部包时会拾取内部包的

Move.toml

。

要依赖同级包，在

Move.toml

中使用

local

路径：

toml

undefined

packages/examples/Move.toml

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

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

undefined

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

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

undefined

Move.toml (current format — Sui CLI v1.63+)

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

The new package management format introduced in Sui CLI v1.63 resolves the Sui framework dependency automatically. You do not need to specify it in

[dependencies]

. A minimal

Move.toml

is:

toml

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

Do not add a

[dependencies]

section for the Sui framework or MoveStdlib — the 2024 edition resolves them automatically. Do not add or suggest a

Sui = { git = "..." }

dependency line — this is a legacy format that errors out on current CLI versions. Only add

[dependencies]

when you need third-party or local packages (e.g., MVR dependencies).

Migrating from
[addresses]
: The old

[addresses]

section with

my_project = "0x0"

is no longer needed and should be removed. If your project previously used

[addresses]

to set package addresses for different networks, replace it with an

[environments]

section that maps environment names to chain IDs:

toml

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

Sui CLI v1.63中引入的新包管理格式会自动解析Sui框架依赖，无需在

[dependencies]

中指定。最简版

Move.toml

如下：

toml

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

请勿为Sui框架或MoveStdlib添加

[dependencies]

章节——2024版本会自动解析它们。请勿添加或建议

Sui = { git = "..." }

依赖行——这是旧版格式，在当前CLI版本中会报错。仅当需要第三方或本地包（如MVR依赖）时，才添加

[dependencies]

。

从
[addresses]
迁移：旧版的

[addresses]

章节（包含

my_project = "0x0"

）已不再需要，应删除。如果你的项目之前使用

[addresses]

为不同网络设置包地址，请替换为

[environments]

章节，将环境名称映射到链ID：

toml

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

Module declaration (2024 edition)

模块声明（2024版本）

With

edition = "2024"

, use single-line module declarations — no curly braces:

move

module my_project::my_module;

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

Do not use the old curly-brace syntax (

module my_project::my_module { ... }

). The 2024 edition treats the entire file as the module body after the semicolon.

使用

edition = "2024"

时，使用单行模块声明——无需大括号：

move

module my_project::my_module;

// 导入、结构体和函数在顶层后续编写
use sui::object::UID;

请勿使用旧版大括号语法（

module my_project::my_module { ... }

）。2024版本将分号后的整个文件视为模块主体。

Published.toml and Move.lock

Published.toml和Move.lock

After publishing, the toolchain creates or updates:

Published.toml
: Tracks your published package addresses per environment. Contains
```
published-at
```
and
```
upgrade-capability-id
```
values for each network.
Move.lock
: Auto-generated lock file that pins every resolved dependency to a specific git revision and records manifest digests. Do not edit manually. Commit this to version control.

To publish to a different environment (for example, after publishing to Testnet, now deploying to Devnet), switch environments and publish again. Each network gives the package a separate ID. The

Published.toml

tracks both.

发布后，工具链会创建或更新以下文件：

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

要发布到不同环境（例如已发布到Testnet，现在部署到Devnet），切换环境并重新发布。每个网络会为包分配单独的ID，

Published.toml

会跟踪这两个ID。

Inspecting Move.lock

查看Move.lock

Move.lock

contains one

[pinned.<env>.<Dependency>]

section per resolved dependency per environment. Each section records the git source, revision, manifest digest, and dependency graph. Example:

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" }

If
```
Move.lock
```
pins a different environment than you expect, or revisions look outdated, delete
```
Move.lock
```
and run
```
sui move build
```
to regenerate it.
If you see build errors after switching networks or updating the CLI, deleting
```
Move.lock
```
and rebuilding often resolves stale-lock issues.

Move.lock

包含每个环境下每个已解析依赖的

[pinned.<env>.<Dependency>]

章节。每个章节记录git源、版本、清单摘要和依赖图。示例：

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
```
并重新构建通常可解决锁定文件过期的问题。

Using MVR dependencies

使用MVR依赖

The Move Registry (MVR) is an onchain package manager for Sui. Install it with:

bash

suiup install mvr

Add an MVR dependency using the CLI:

bash

mvr add @org/package --network testnet

Or declare it directly in

Move.toml

toml

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

The

r.mvr

key tells the resolver to look up the package in the onchain Move Registry instead of fetching from a git URL. Prefer MVR dependencies over git URLs when the package is published to the registry — they are versioned, auditable, and do not depend on git history.

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

bash

suiup install mvr

使用CLI添加MVR依赖：

bash

mvr add @org/package --network testnet

或直接在

Move.toml

中声明：

toml

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

r.mvr

键告诉解析器在链上Move Registry中查找包，而非从git URL获取。当包已发布到注册表时，优先使用MVR依赖而非git URL——它们支持版本化、可审计，且不依赖git历史。

Common dependency and build issues

常见依赖与构建问题

"Dependency 'Sui' is a legacy system name": Remove the
```
Sui = { git = "..." }
```
line from
```
[dependencies]
```
. The current CLI resolves the Sui framework automatically. This error occurs when using the old git-based dependency format.
"Packages with old dependencies" error: Your CLI version does not match the network. The new package management format introduced in Sui CLI v1.63 changed how dependencies are resolved. Run
```
suiup update sui@testnet
```
then
```
suiup switch sui@testnet
```
to get the latest CLI.
"Cannot upgrade package without having a published id": You need a
```
published-at
```
value in
```
Published.toml
```
to upgrade. This is created automatically after your first
```
sui client publish
```
. If you migrated from the old format, make sure the
```
Published.toml
```
file exists and contains the correct package address.
"Could not determine the correct dependencies": The build requires a
```
--build-env
```
flag or an
```
[environments]
```
section in
```
Move.toml
```
. Add the
```
[environments]
```
section with your target chain IDs.
Edition mismatch: If you get errors about
```
public struct
```
syntax, set
```
edition = "2024"
```
in
```
Move.toml
```
. The
```
legacy
```
edition does not support Move 2024 features like public struct visibility.
Old Move.toml format: If you are using the pre-v1.63 format with
```
[addresses]
```
and
```
published-at
```
inside
```
Move.toml
```
, migrate to the new format: remove
```
[addresses]
```
, add
```
[environments]
```
, and let the toolchain manage
```
Published.toml
```
.

"Dependency 'Sui' is a legacy system name"： 从
```
[dependencies]
```
中删除
```
Sui = { git = "..." }
```
行。当前CLI会自动解析Sui框架。此错误在使用旧版基于git的依赖格式时出现。
"Packages with old dependencies"错误： 你的CLI版本与网络不匹配。Sui CLI v1.63中引入的新包管理格式改变了依赖解析方式。运行
```
suiup update sui@testnet
```
，然后运行
```
suiup switch sui@testnet
```
获取最新CLI。
"Cannot upgrade package without having a published id"： 升级需要
```
Published.toml
```
中的
```
published-at
```
值。首次运行
```
sui client publish
```
后会自动创建该值。如果是从旧版格式迁移，请确保
```
Published.toml
```
文件存在且包含正确的包地址。
"Could not determine the correct dependencies"： 构建需要
```
--build-env
```
标志或
```
Move.toml
```
中的
```
[environments]
```
章节。添加包含目标链ID的
```
[environments]
```
章节。
版本不匹配： 如果遇到关于
```
public struct
```
语法的错误，请在
```
Move.toml
```
中设置
```
edition = "2024"
```
。旧版（legacy）不支持Move 2024的特性，比如公共结构体可见性。
旧版Move.toml格式： 如果使用v1.63之前的格式（包含
```
[addresses]
```
和
```
Move.toml
```
内的
```
published-at
```
），请迁移到新版格式：删除
```
[addresses]
```
，添加
```
[environments]
```
，并让工具链管理
```
Published.toml
```
。

Rules

规则

Use
```
public(package)
```
visibility for non-library functions.
```
public
```
function signatures cannot be deleted or modified in upgrades.
Struct definitions cannot be deleted, modified, or have abilities added through upgrades.
Objects cannot exceed 256 KB. Avoid ever-growing vectors inside objects.

非库函数使用
```
public(package)
```
可见性。
```
public
```
函数签名在升级时不能删除或修改。
结构体定义在升级时不能删除、修改或添加能力。
对象大小不能超过256 KB。避免在对象内使用不断增长的向量。",