入门(Getting Started)
安装 Rive CLI、创建项目,并打开实时预览。完成本指南后,你会得到一个可用 Rive 运行时加载的 .riv 文件。
1. 安装 CLI
CLI 可在搭载 Apple Silicon 的 macOS、Linux x86_64 以及 Windows 上运行。
Installer
curl -fsSL https://releases.rive.app/cli/install.sh | sh
把 CLI 加入 PATH,以便在每个新 shell 中都能使用 rive 命令,然后重新加载当前 shell 使改生效:
echo 'export PATH="$HOME/.rive/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Windows
irm https://releases.rive.app/cli/install.ps1 | iex
Homebrew
brew install --cask rive-app/tap/rive-cli
rive update、rive switch 和 rive uninstall 需要 ~/.rive 下的安装器构建,因此它们不适用于 Homebrew 安装。请改用 brew 管理 Homebrew 安装,例如 brew upgrade 和 brew uninstall --cask rive-cli。
运行 rive doctor 检查安装是否成功。
2. 创建项目
rive create myproject
这会写入一份 rive.yaml、供编码代理使用的 AGENTS.md 和 CLAUDE.md、一份 .gitignore,以及一份 scene.rml。scene.rml 与编辑器新建文件时给出的画面相同:一个画板、一条时间轴,以及加载时播放该时间轴的状态机。你添加并打上关键帧的形状会立即开始动画,无需额外配置。
之后放进文件夹的其他内容会按扩展名被自动拾取:.luau 脚本、.wgsl 着色器、图像和字体。生成的 rive.yaml 会设置 name 并打开构建日志;rive.yaml 中的其余项都是可选的。
3. 打开预览窗口
rive myproject
这会打开一个显示场景的窗口,并监视该目录。保存任意文件后,它会重建并重新加载,同时写出 myproject/build/myproject.riv——你可以用运行时加载的文件。
新项目里还没有绘制任何内容,因此你会看到一个深色矩形。让它在一个终端里保持运行,同时在另一个终端里编辑。
若要构建但不打开窗口,使用 rive myproject --publish,这会写出已签名的 .riv。若只要检查项目能否编译、不写出任何文件,使用 --verify 标志。
从账户中的文件起步
如果作品已经存在于你的 Rive 账户中,把它下载到项目里:
rive create myproject --from-remote-file
rive myproject
CLI 会列出你的项目和文件供你选择;需要给脚本用这些 id 时,rive ls 会以非交互方式打印同样的 id。rive.yaml 会记录该链接,因此 rive push 可以把改动发回,rive pull 则可以把编辑器中的改动拉下来。这需要先用 rive login 登录。
从导出的 .rev 起步
你也可以把从编辑器导出的 .rev 转换成项目,这条路径不需要登录:
rive create myproject --from-rev=myfile.rev # --from-rev 接受 .rev 的路径
rive myproject
场景会写成 scene.rml,每个脚本、着色器和资源都会写成各自的文件,布局方式与编辑器 Assets 面板中的一致。你还会得到常规的 rive.yaml、AGENTS.md 和 .gitignore,从这一步起它就是一个普通项目。
项目名必须为空或全新。省略项目名时会使用 .rev 自身的名称,因此 myfile.rev 会变成 myfile/。
登录
创建、预览或在本地构建项目不需要登录。当你需要发布文件,或导出可在 Rive 编辑器中打开的 .rev 时再登录:
rive login
--publish 需要账户,因为它会通过 Rive 的 API 为文件签名;--rev 会导出 .rev,同样需要账户。其余操作都在本地运行,退出登录以及离线时也能使用。
如果你还不是任何工作区的成员,CLI 还会在你登录时为你创建一个 Free 工作区。此后,尚未绑定到文件的项目所做的发布会计入该工作区,因为它是你担任编辑者的唯一工作区。
包含脚本、且最终要用于 Web 的文件必须用 --publish 构建。未签名的脚本会被 CDN 和 Web 运行时拒绝。不含脚本的文件不受影响。
--publish 在本次发布计入的工作区使用 Cadet 或更高套餐 时,会写出没有水印的 .riv。否则会加水印。用 rive push 绑定到文件的项目,计入该文件所在的工作区。其他项目计入你用 rive workspace 选择的工作区,或者你担任编辑者的唯一工作区。参见哪个工作区计入。
导出项目
准备好分享或导出 CLI 项目时,可以按目标选择路径:
| 你想要 | 导出 | 命令 |
|---|---|---|
| 在 Rive 编辑器中继续做 | 账户中的文件,或 .rev | rive push,或 --rev |
| 在应用中用 Rive 运行时加载 | 一个 .riv | --publish |
推送到 Rive 编辑器
要在编辑器中打开该项目,把它推送到你 Rive 账户中的一个文件:
rive login # 每台机器一次
rive push myproject # 第一次 push 会询问要在哪个 Rive 项目中创建文件
该文件会像其他文件一样出现在编辑器的文件浏览器中,rive.yaml 会记录该链接,之后的 push 会更新同一个文件。用 rive pull 把编辑器中的改动拉回项目。push、修订和冲突如何工作,见推送到 Rive 文件。
若更想导出 .rev:
rive myproject --rev=myproject.rev
rive push 和导出 --rev 都需要 CLI 已登录。
为运行时构建 .riv
要在应用中加载该项目,构建一个 .riv,再像其他 Rive 文件一样加入你的工程:
rive myproject --publish # 已签名的 .riv,需要 rive login
这会写到 myproject/build/myproject.riv,或写到 rive.yaml 中 output.dir 指定的目录。之后按你所用平台的运行时指南加载它。
若要分享可播放的链接而不是文件,rive myproject --publish=web 会把构建托管成公开页面。参见发布(Publishing)。
更多资源
- RML - 描述场景的标记语言
- AI 代理(AI Agents) - 把项目交给 Claude Code 或 Cursor
- 示例(Examples) - 可起步的示例项目、无窗口渲染,以及 CI
- 命令(Commands) - 全部命令与标志