跳至主要內容

Vagrant 实用指南：常用命令与核心配置详解（基于 VirtualBox）

佳哥很忙2021/2/16文章VagrantVirtualBox大约 11 分钟

概述

Vagrant 是一款基于 Ruby 开发的虚拟化环境管理工具，核心价值在于 “标准化开发环境”—— 通过配置文件（Vagrantfile）定义虚拟机参数（系统镜像、网络、硬件资源等），实现 “一键创建、跨平台复用” 的开发环境，彻底解决 “本地环境能跑，线上 / 同事电脑跑不了” 的问题。

Vagrant 本身不提供虚拟化能力，需依赖第三方虚拟化软件（如 VirtualBox、VMware、Hyper-V），其中 VirtualBox 因开源免费、跨平台（Windows/macOS/Linux），是最常用的搭配。它的核心工作流可概括为：
编写配置文件（Vagrantfile）→ 一键启动虚拟机（vagrant up）→ 无缝连接开发（vagrant ssh）→ 环境销毁/暂停（vagrant destroy/suspend）

无论是个人开发（避免本地环境混乱），还是团队协作（统一开发环境），Vagrant 都能大幅提升效率。本文将系统梳理 Vagrant 的常用命令（覆盖生命周期管理）与核心配置（网络、存储、硬件、自动化部署），帮你快速上手并灵活定制开发环境。

一、Vagrant 核心命令：覆盖虚拟机全生命周期

Vagrant 的命令均通过终端执行，围绕 “虚拟机从创建到销毁” 的全流程设计，以下按使用频率和场景分类讲解，标注关键参数与注意事项。

1. 环境初始化：创建 Vagrantfile

初始化命令用于在指定目录生成默认的 Vagrantfile（配置文件），后续所有虚拟机配置均通过该文件修改。

命令格式：

# 在当前目录初始化，指定基础镜像（box）
vagrant init [基础镜像名称]

关键说明：

  • 基础镜像（Box）：Vagrant 的 “虚拟机模板”，包含操作系统（如 Ubuntu 20.04、CentOS 7）及基础配置，需先从 Vagrant Cloud 搜索合适的 Box（如 ubuntu/focal64 表示 Ubuntu 20.04 64 位）；
  • 若不指定 Box（直接执行 vagrant init），会生成空的 Vagrantfile，需手动在文件中配置 config.vm.box。

示例：初始化 Ubuntu 20.04 环境

# 1. 创建并进入项目目录
mkdir vagrant-ubuntu && cd vagrant-ubuntu

# 2. 初始化，指定基础镜像为 ubuntu/focal64
vagrant init ubuntu/focal64

执行后，当前目录会生成 Vagrantfile 文件，后续可编辑该文件定制虚拟机。

2. 虚拟机启动与连接：up & ssh

vagrant up 是最核心的命令之一，用于根据 Vagrantfile 配置启动虚拟机（首次启动会自动下载指定的 Box，需耐心等待）；vagrant ssh 用于通过 SSH 连接已启动的虚拟机（无需手动输入用户名密码，Vagrant 已默认配置免密登录）。

####（1）启动虚拟机

# 启动当前目录 Vagrantfile 定义的虚拟机
vagrant up

# 可选：指定虚拟机名称（多机配置时使用，默认单机会自动命名为 "default"）
vagrant up [虚拟机名称]

启动过程说明：

  • 首次启动：自动下载 Box（存储路径：Windows 为 C:\Users\用户名.vagrant.d\boxes，macOS/Linux 为 ~/.vagrant.d/boxes）→ 创建虚拟机 → 配置网络 / 共享目录 → 执行初始化脚本；

  • 非首次启动：直接恢复虚拟机（从关机 / 暂停状态启动），无需重复下载 Box。

（2）连接虚拟机

# SSH 连接当前目录的虚拟机（需先执行 vagrant up 启动）
vagrant ssh

# 连接指定名称的虚拟机（多机配置时）
vagrant ssh [虚拟机名称]

连接后说明：

  • 默认登录用户为 vagrant，拥有 sudo 免密权限（执行 sudo 命令 无需输入密码）；
  • 虚拟机内的 /vagrant 目录默认是 “本地目录与虚拟机的共享目录”（本地目录即 Vagrantfile 所在目录），可直接在该目录下共享文件（如本地编写代码，虚拟机内运行）。

3. 虚拟机状态管理：status & 启停控制

在开发过程中，常需查看虚拟机状态或临时暂停 / 恢复 / 关机，对应命令如下：

命令功能说明适用场景
vagrant status查看当前虚拟机状态（running/stopped/suspended）不确定虚拟机是否启动时
vagrant suspend暂停虚拟机（内存数据保存到磁盘，下次启动快）临时离开，想保留当前开发状态
vagrant resume恢复暂停的虚拟机继续之前的开发工作
vagrant halt正常关机（类似物理机关机，内存数据清空）长期不使用，想释放资源
vagrant destroy销毁虚拟机（删除虚拟机文件，仅保留 Vagrantfile）环境不再需要，彻底释放磁盘空间

示例：常用状态操作

# 查看虚拟机状态
vagrant status  # 输出：default: running (virtualbox) 表示已启动

# 暂停虚拟机
vagrant suspend

# 恢复暂停的虚拟机
vagrant resume

# 正常关机
vagrant halt

# 销毁虚拟机（执行前需确认，会删除所有虚拟机内数据）
vagrant destroy  # 提示 "Are you sure? [y/N]"，输入 y 确认

注意：

  • vagrant destroy 会彻底删除虚拟机（包括内部安装的软件、数据），但不会删除 Vagrantfile 和本地共享目录的文件，若需重新创建虚拟机，执行 vagrant up 即可；
  • 若虚拟机启动失败（如端口冲突），可先执行 vagrant halt 或 vagrant destroy 清理状态，再重新启动。

4. 配置与环境更新：reload & provision

当修改 Vagrantfile 配置（如网络、硬件资源）或需要重新执行初始化脚本时，需用到以下命令：

（1）重新加载配置

# 重启虚拟机并加载最新的 Vagrantfile 配置
vagrant reload

# 可选：重启时强制重新执行初始化脚本（provision）
vagrant reload --provision

关键说明：

  • 修改 Vagrantfile 后（如调整内存、端口映射），必须执行 vagrant reload 才能让配置生效；
  • 若仅修改了 “初始化脚本”（如 provision 配置），无需重启虚拟机，可直接执行 vagrant provision。

（2）重新执行初始化脚本

# 对已启动的虚拟机，重新执行 Vagrantfile 中的 provision 配置（如安装软件）
vagrant provision

适用场景：

  • 初始化脚本（如 install.sh）修改后，无需重启虚拟机即可应用更新；
  • 新增软件安装需求，不想销毁虚拟机重新创建，直接通过 provision 补充安装。

5. 全局管理与验证：global-status & validate

当同时管理多个 Vagrant 环境时，可通过全局命令查看所有虚拟机状态；配置 Vagrantfile 后，可先验证语法是否正确，避免启动失败。

（1）查看全局虚拟机状态

# 查看当前系统中所有 Vagrant 管理的虚拟机（无论所在目录）
vagrant global-status

输出示例：

id       name   provider   state    directory
-------------------------------------------------------------------------
abc123   default virtualbox running  /Users/yourname/vagrant-ubuntu
def456   centos virtualbox stopped  /Users/yourname/vagrant-centos
  • 可通过 id 或 name 操作指定虚拟机（如 vagrant ssh abc123 连接指定虚拟机）；
  • 执行 vagrant global-status --prune 可清理已删除虚拟机的无效记录。

（2）验证 Vagrantfile 语法

# 检查当前目录的 Vagrantfile 是否存在语法错误
vagrant validate

作用：

  • 若 Vagrantfile 中存在语法错误（如括号不匹配、参数错误），执行 vagrant up 会失败，提前用 vagrant validate 验证可快速定位问题。

二、Vagrant 核心配置：Vagrantfile 关键参数

Vagrantfile 是 Vagrant 的配置核心，采用 Ruby 语法（但无需掌握 Ruby，按模板修改即可），以下讲解开发中最常用的配置项，结合示例说明用途与注意事项。

配置文件结构说明

默认 Vagrantfile 包含大量注释，核心配置在 Vagrant.configure("2") do |config| ... end 代码块中，所有自定义配置均需写在该块内，示例框架如下：

Vagrant.configure("2") do |config|
  # 基础镜像配置
  config.vm.box = "ubuntu/focal64"

  # 主机名配置
  config.vm.hostname = "dev-ubuntu"

  # 网络配置（端口映射、私有网络等）
  # ...

  # 硬件资源配置（内存、CPU）
  # ...

  # 共享目录配置
  # ...

  # 自动化部署配置（provision）
  # ...
end

1. 基础镜像配置：指定 Box

# 核心配置：指定虚拟机的基础镜像（Box 名称或本地路径）
config.vm.box = "ubuntu/focal64"

# 可选：指定 Box 的版本（不指定则默认使用最新版）
config.vm.box_version = "202405.13.0"

# 可选：指定 Box 的下载源（若官方源下载慢，可配置国内镜像）
config.vm.box_url = "https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/vagrant/focal/current/focal-server-cloudimg-amd64-vagrant.box"

说明：

  • Box 名称需与 Vagrant Cloud 一致（如 centos/7 表示 CentOS 7）；
  • 国内用户推荐配置 box_url 为清华镜像、阿里云镜像等，加速下载（如 Ubuntu 镜像可参考 清华源文档）。

2. 网络配置：端口映射与私有网络

Vagrant 支持三种网络模式：端口映射（Forwarded Port）、私有网络（Private Network）、公有网络（Public Network），其中前两种最常用。

（1）端口映射（本地主机访问虚拟机服务）

将虚拟机的端口映射到本地主机的端口，实现 “通过本地端口访问虚拟机内服务”（如虚拟机内启动 Nginx，本地通过 localhost:80 访问）：

# 端口映射：guest（虚拟机端口）80 → host（本地端口）8080
config.vm.network "forwarded_port", guest: 80, host: 8080, auto_correct: true

参数说明：

  • guest: 80：虚拟机内服务的端口（如 Nginx 默认端口 80）；
  • host: 8080：本地主机的端口（通过 localhost:8080 访问虚拟机服务）；
  • auto_correct: true：若本地端口 8080 已被占用，自动分配其他可用端口，避免启动失败。

（2）私有网络（虚拟机与本地主机 / 其他虚拟机通信）

为虚拟机分配一个 “仅本地可见的私有 IP”，实现 “本地主机直接通过 IP 访问虚拟机”（如 192.168.1.100），且同一私有网络内的虚拟机可互相通信：

# 私有网络：固定 IP（推荐，便于记忆）
config.vm.network "private_network", ip: "192.168.1.100"

# 可选：动态 IP（由 VirtualBox DHCP 自动分配，每次启动可能变化）
# config.vm.network "private_network", type: "dhcp"

适用场景：

  • 虚拟机内启动数据库、后端服务，本地开发环境（如 IDE）直接通过私有 IP 连接（比端口映射更灵活）；
  • 多机配置（如一个前端虚拟机、一个后端虚拟机），需要虚拟机间互相访问。

3. 硬件资源配置：内存与 CPU

通过 virtualbox provider 配置虚拟机的硬件资源（内存、CPU 核心数），避免资源占用过高或不足：

# 针对 VirtualBox 的硬件配置
config.vm.provider "virtualbox" do |vb|
  # 内存：4096 MB（4GB，根据本地硬件调整，建议不超过本地内存的 50%）
  vb.customize ["modifyvm", :id, "--memory", "4096"]

  # CPU 核心数：4 核（建议不超过本地 CPU 核心数的一半，避免本地卡顿）
  vb.customize ["modifyvm", :id, "--cpus", "4"]

  # 可选：启用显存（若虚拟机需要图形界面，如 Ubuntu Desktop）
  # vb.customize ["modifyvm", :id, "--vram", "128"]

  # 可选：设置虚拟机名称（在 VirtualBox 界面中显示）
  # vb.name = "Dev-Ubuntu-20.04"
end

注意：

  • 配置的内存和 CPU 需根据本地硬件调整（如本地 8GB 内存，虚拟机建议设为 4GB；本地 8 核 CPU，虚拟机建议设为 4 核）；
  • 修改硬件配置后，需执行 vagrant reload 才能生效。

4. 共享目录配置：本地与虚拟机文件共享

共享目录用于实现 “本地目录与虚拟机目录双向同步”—— 本地修改文件后，虚拟机内实时生效；虚拟机内生成的文件，本地也能直接访问，是开发中核心需求之一。

（1）禁用默认共享目录

Vagrant 默认会将 Vagrantfile 所在目录共享到虚拟机的 /vagrant 目录，若不需要可禁用：

# 禁用默认共享目录（/vagrant）
config.vm.synced_folder ".", "/vagrant", enabled: false

（2）自定义共享目录

配置自定义的本地目录与虚拟机目录映射，支持指定权限、同步方式等：

# 自定义共享目录：本地 "./share" 目录 → 虚拟机 "/home/vagrant/share" 目录
config.vm.synced_folder "./share", "/home/vagrant/share",
  create: true,  # 若虚拟机目录不存在，自动创建
  owner: "vagrant",  # 虚拟机目录的所有者（默认 vagrant）
  group: "vagrant",  # 虚拟机目录的所属组（默认 vagrant）
  mount_options: ["dmode=755", "fmode=644"]  # 目录权限 755，文件权限 644

说明：

  • 本地目录 ./share 需提前创建（或通过 create: true 让 Vagrant 自动创建）；
  • 共享目录支持实时同步（本地修改文件，虚拟机内立即可见），适合存放开发代码、配置文件等。

5. 自动化部署：Provision（一键安装软件）

Provision 是 Vagrant 的 “自动化部署” 功能，支持通过 Shell 脚本、Ansible、Chef 等方式，在虚拟机启动时自动安装软件、配置环境（如安装 Nginx、Python、数据库等），避免手动操作，实现 “一键生成完整开发环境”。

最常用的是 Shell 脚本 Provision，示例如下：

# 通过 Shell 脚本自动化部署（脚本路径为本地 "./provision/install.sh"）
config.vm.provision "shell", path: "./provision/install.sh", privileged: true

参数说明：

  • path: "./provision/install.sh"：本地 Shell 脚本路径（需提前创建该脚本，编写软件安装命令）；
  • privileged: true：以 root 权限执行脚本（默认 true，若无需 root 权限可设为 false）。

示例 Shell 脚本（install.sh）：安装 Nginx 与 Python

#!/bin/bash
# 虚拟机启动时自动执行该脚本，安装 Nginx 和 Python3

# 更新 apt 源（Ubuntu 系统）
apt update -y

# 安装 Nginx
apt install -y nginx

# 启动并设置 Nginx 开机自启
systemctl start nginx
systemctl enable nginx

# 安装 Python3 与 pip
apt install -y python3 python3-pip

# 验证安装
echo "Nginx 版本：$(nginx -v 2