setup 命令

从 vx.toml 安装所有项目工具。

语法

vx setup [OPTIONS]

描述

vx setup 命令是加入项目或克隆仓库后首先要运行的命令。它读取项目的 vx.toml 配置并：

1. 检查哪些工具已安装
2. 将所有缺失的工具安装到 ~/.vx/store/
3. 报告安装状态

这确保所有团队成员拥有完全相同的工具版本。

选项

选项	说明
-f, --force	强制重新安装所有工具
--dry-run	预览操作而不执行
-v, --verbose	显示详细输出
--no-parallel	禁用并行安装

使用场景

场景 1：初始项目设置

克隆带有 vx.toml 的项目时：

git clone https://github.com/example/project.git
cd project
vx setup

输出：

🚀 VX Development Environment Setup

Checking tool status...

Tools:
  ✓ node@20.10.0 (installed)
  ✗ uv@0.5.14 (missing)
  ✗ go@1.21.5 (missing)

Installing 2 tool(s)...
  ✓ uv@0.5.14
  ✓ go@1.21.5

✓ Successfully installed 2 tool(s) in 12.3s

Next steps:
  1. Enter dev environment: vx dev
  2. Or run tools directly: vx <tool> [args]

Available scripts:
  vx run dev -> npm run dev
  vx run test -> pytest

场景 2：CI/CD 流水线

在 CI/CD 中运行 vx setup 确保工具可用：

# GitHub Actions
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: 安装 vx
        run: curl -fsSL https://get.vx.dev | bash

      - name: 安装项目工具
        run: vx setup

      - name: 构建
        run: vx dev -c "npm run build"

场景 3：强制重新安装

如果怀疑工具损坏或需要全新安装：

vx setup --force

这将重新安装所有工具，即使它们看起来已安装。

场景 4：预览更改

查看将安装什么而不实际安装：

vx setup --dry-run

输出：

🚀 VX Development Environment Setup

Tools:
  ✓ node@20.10.0 (installed)
  ✗ uv@0.5.14 (missing)
  ✗ go@1.21.5 (missing)

Would install 2 tool(s):
  - uv@0.5.14
  - go@1.21.5

配置

setup 从 vx.toml 读取：

[tools]
node = "20"
uv = "latest"
go = "1.21"

[settings]
auto_install = true    # 在 vx dev 中自动安装缺失工具
parallel_install = true # 并行安装工具

[scripts]
dev = "npm run dev"
test = "pytest"
build = "npm run build"

工具存储

所有工具都安装到全局 store ~/.vx/store/：

~/.vx/
├── store/
│   ├── node/
│   │   ├── 20.10.0/
│   │   └── 18.19.0/
│   ├── uv/
│   │   └── 0.5.14/
│   └── go/
│       └── 1.21.5/
└── bin/

这种内容寻址存储允许：

• 多个项目共享相同的工具版本
• 不浪费磁盘空间在重复文件上
• 快速切换版本

工作流：setup vs dev

┌─────────────────────────────────────────────────────────────────┐
│                        项目工作流                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   1. 克隆项目                                                    │
│      git clone https://github.com/example/project.git            │
│                                                                  │
│   2. 安装工具（一次性）                                          │
│      vx setup                                                    │
│                                                                  │
│   3. 进入开发环境（日常）                                        │
│      vx dev                                                      │
│      # 或                                                        │
│      eval "$(vx dev --export)"                                   │
│                                                                  │
│   4. 运行项目脚本                                                │
│      vx run dev                                                  │
│      vx run test                                                 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

命令	用途	使用时机
vx setup	安装工具	首次使用、vx.toml 变更后
vx dev	进入环境	日常开发
vx dev --export	在当前 shell 激活	IDE 集成、脚本
vx run <script>	运行定义的脚本	构建、测试、部署

退出码

代码	含义
0	成功 - 所有工具已安装
1	错误 - 部分工具安装失败

提示

1. git pull 后运行：如果 vx.toml 可能已更改：

   git pull && vx setup

2. 在 git hooks 中使用：checkout 时自动设置：

   # .git/hooks/post-checkout
   #!/bin/sh
   vx setup --dry-run | grep -q "missing" && vx setup

3. 调试时使用详细模式：

   vx setup --verbose

4. 并行更快：默认情况下，工具并行安装。仅在遇到问题时使用 --no-parallel。

参见

• init - 初始化项目配置
• dev - 进入开发环境
• sync - 同步工具与配置