🔍搜索⌘K
>_ ~/佳哥很忙的技术博客

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

📅 2021/2/16 ⏱ ≈ 9 分钟 Container

概述

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