GeekIt

Packer命令速查

安装与插件、fmt 与 validate、build 参数、HCL2 模板、变量、source 构建器、provisioner、post-processor、调试与报错排查等 134 条命令

共 134 条命令 · 12 类场景 · 点击右侧图标可复制

命令 / 配置说明复制
packer version查看 Packer 版本,1.7+ 才支持插件体系
packer -v版本简写
brew install hashicorp/tap/packermacOS 安装
apt install packerDebian/Ubuntu 安装(需官方源)
dnf install packerRHEL/CentOS 安装
choco install packerWindows 安装
export PACKER_LOG=1开启调试日志,排查构建失败首选
export PACKER_LOG_PATH=/tmp/packer.log日志落盘,便于完整查看
export PACKER_PLUGIN_PATH=/opt/packer/plugins自定义插件目录,离线环境使用
export CHECKPOINT_DISABLE=1关闭版本检查上报,内网环境常用
packer -help查看全部子命令
命令 / 配置说明复制
packer init .按 required_plugins 下载插件(1.7+ 必须执行)
packer init -upgrade .升级插件到允许的最新版本
packer plugins installed列出已安装插件与版本
packer plugins required查看当前模板依赖的插件
packer plugins install github.com/hashicorp/amazon手动安装插件
packer plugins remove github.com/hashicorp/vsphere卸载插件
packer {} 块中的 required_plugins 锁定版本例如 version = ">= 1.2.0"
插件目录默认在 ~/.config/packer/pluginsCI 中可缓存该目录加速构建
packer init 失败先看网络与代理GitHub 不可达时用 PACKER_PLUGIN_PATH 离线安装
命令 / 配置说明复制
packer fmt .格式化 HCL2 模板
packer fmt -recursive .递归格式化子目录
packer fmt -check -recursive .只检查不修改,CI 中返回非零即失败
packer fmt -diff .显示格式差异
packer validate .校验模板语法与变量,需先 init
packer validate -syntax-only .只做语法校验,速度更快
packer validate -var-file=prod.pkrvars.hcl .带变量校验,能发现变量缺失
packer validate -except=source.docker.web .校验时排除指定 source
packer hcl2_upgrade template.json把旧版 JSON 模板升级为 HCL2
validate + fmt 是 CI 第一道门挡掉大部分拼写与结构错误
命令 / 配置说明复制
packer build .构建当前目录模板
packer build template.pkr.hcl指定单个模板文件
packer build -var "version=1.2.3" .命令行传变量
packer build -var-file=prod.pkrvars.hcl .使用变量文件
packer build -only=source.amazon-ebs.web .只构建指定 source
packer build -except=source.docker.web .排除指定 source
packer build -force .跳过交互确认,覆盖已存在的产物
packer build -debug .逐步确认每一步,并禁用并行
packer build -on-error=ask .出错时询问:重试、清理或中止
packer build -on-error=cleanup .出错自动清理临时资源(CI 推荐)
packer build -on-error=abort .出错立即中止并保留现场便于排查
packer build -parallel-builds=1 .串行构建,减少资源争抢
packer build -timestamp-ui .输出时间戳,便于分析各阶段耗时
packer build -machine-readable .机器可读输出,便于流水线解析
命令 / 配置说明复制
packer { required_plugins { amazon = { source = "github.com/hashicorp/amazon" version = ">= 1.2.0" } } }模板头部:声明插件与版本约束
variable "region" { type = string default = "ap-east-1" }变量定义,支持 type/default/validation
source "amazon-ebs" "web" { ami_name = "web-{{timestamp}}" instance_type = "t3.micro" region = var.region source_ami = data.amazon-ami.ubuntu.id ssh_username = "ubuntu" }构建器定义,名称用 source.<type>.<name> 引用
build { sources = ["source.amazon-ebs.web"] provisioner "shell" { inline = ["sudo apt-get update -y"] } }build 块把 source 与 provisioner 串起来
data "amazon-ami" "ubuntu" { filters = { name = "ubuntu/images/*22.04*" } most_recent = true }data 源动态查询基础镜像,避免硬编码 AMI
locals { app_version = "1.2.3" }局部变量,做命名与拼接
{{timestamp}} 与 {{uuid}} 是模板函数常用于生成唯一镜像名
provisioner "shell" { script = "./scripts/install.sh" }外置脚本比 inline 更易维护
post-processor "manifest" { output = "manifest.json" }输出产物清单,后续流水线读取镜像 ID
一个模板可包含多个 source 与多个 build多云/多平台镜像可以一次构建
命令 / 配置说明复制
packer build -var "image_version=2.0.1" .单变量传递
packer build -var-file=common.pkrvars.hcl -var-file=prod.pkrvars.hcl .多变量文件叠加,后者覆盖前者
export PKR_VAR_image_version=2.0.1环境变量传值,CI 中最安全(不进命令行历史)
*.auto.pkrvars.hcl 自动加载同目录下无需显式 -var-file
variable "token" { type = string sensitive = true }标记敏感变量,日志中会打码
validation { condition = length(var.region) > 0 error_message = "region 不能为空" }变量校验,提前拦截非法值
var.region 在 source 中引用变量作用域是全模板
local.app_version 引用 localslocals 与 var 前缀不同
优先级:PKR_VAR_ 环境变量 < -var-file < -var排查“值没生效”时按此顺序确认
敏感信息用 Vault 插件或 CI 变量注入不要提交到仓库
命令 / 配置说明复制
source "amazon-ebs" "web" { ... }AWS:启动实例、provision、打包 AMI
source "googlecompute" "web" { ... }GCP 镜像构建
source "azure-arm" "web" { ... }Azure 托管镜像
source "docker" "web" { image = "ubuntu:22.04" commit = true }Docker 镜像构建,CI 最常用
source "qemu" "web" { iso_url = "..." iso_checksum = "..." }QEMU/KVM 本地虚拟机构建
source "vmware-iso" "web" { ... }VMware 镜像构建
source "virtualbox-iso" "web" { ... }VirtualBox 镜像构建
source "file" "conf" { source = "app.conf" destination = "/tmp/app.conf" }仅生成文件产物,做配置分发
source "null" "check" { communicator = "none" }不创建资源,只跑本地命令
source "amazon-ebssurrogate" "web" { ... }只挂数据盘构建,适合特殊分区需求
source 名称决定 -only 的取值写 build 与流水线时保持一致
命令 / 配置说明复制
provisioner "shell" { inline = ["sudo apt-get update -y", "sudo apt-get install -y nginx"] }内联命令,适合少量步骤
provisioner "shell" { script = "./scripts/setup.sh" }执行单个脚本
provisioner "shell" { scripts = ["./scripts/01-base.sh", "./scripts/02-app.sh"] }按顺序执行多个脚本
provisioner "shell" { environment_vars = ["APP_ENV=prod"] inline = ["echo $APP_ENV"] }向脚本注入环境变量
provisioner "file" { source = "app.tar.gz" destination = "/tmp/app.tar.gz" }上传文件到构建机
provisioner "shell-local" { inline = ["echo build done"] }在运行 Packer 的本机执行
provisioner "ansible" { playbook_file = "./ansible/site.yml" }调用 Ansible 做复杂配置
provisioner "ansible-local" { playbook_file = "./site.yml" }在构建机内本地执行 Ansible
provisioner "powershell" { inline = ["Install-WindowsFeature Web-Server"] }Windows 镜像配置
provisioner "breakpoint" {}暂停等待确认,调试时插入到关键步骤
provisioner "sleep" { duration = "30s" }等待服务就绪或云初始化完成
only = ["source.amazon-ebs.web"]限定该 provisioner 只对某个 source 生效
provisioner 失败会中断构建脚本内加 set -e 与错误日志更易排查
命令 / 配置说明复制
post-processor "manifest" { output = "manifest.json" strip_path = true }输出产物清单,流水线读取镜像 ID
post-processor "docker-tag" { repository = "registry.example.com/app" tags = ["latest", "1.2.3"] }给 Docker 镜像打标签
post-processor "docker-push" {}推送镜像到仓库
post-processor "compress" { output = "app.tar.gz" }压缩产物
post-processor "checksum" { checksum_types = ["sha256"] }生成校验和文件
post-processor "vagrant" {}生成 Vagrant box
post-processor "amazon-import" {}把 OVA/VMDK 导入为 AMI
post-processor "vsphere" {}上传模板到 vSphere
post-processor 可串联多个 post-processor 按声明顺序执行
manifest 是自动化发布的关键产物避免用 grep 解析构建日志
命令 / 配置说明复制
source "docker" "base" { image = "ubuntu:22.04" commit = true }基于官方镜像构建并提交
changes = ["EXPOSE 8080", "WORKDIR /app", "ENTRYPOINT [\"/app/start.sh\"]"]修改镜像元数据(相当于 Dockerfile 指令)
commit = true 才会生成镜像并交给 post-processor否则仅临时容器内执行命令
source "qemu" "ubuntu" { iso_url = "https://.../ubuntu-22.04.iso" iso_checksum = "sha256:..." disk_size = "10240" format = "qcow2" accelerator = "kvm" }QEMU 构建 Linux 镜像
boot_command = ["<esc><wait>", "linux /casper/vmlinuz --- autoinstall<enter>"]自动安装引导命令,Ubuntu autoinstall 常用
ssh_username = "ubuntu" 与 ssh_timeout = "20m"首次启动较慢,超时要放宽
qemuargs = [["-m", "2048"]]调整内存等 QEMU 参数
accelerator = "kvm" 需要 /dev/kvm 权限CI 容器内通常不可用,改用 tcg 会慢很多
docker build 场景通常比 QEMU 快一个数量级按交付形态选择构建器
命令 / 配置说明复制
PACKER_LOG=1 packer build .打印详细日志,定位插件与通信问题
PACKER_LOG_PATH=/tmp/packer.log PACKER_LOG=1 packer build .日志落盘便于检索
packer build -debug .单步确认并禁用并行,交互排障
packer build -on-error=ask .失败时停下来保留现场
packer console .交互式求值 HCL 表达式(1.7+)
packer build -machine-readable . | tee build.log结构化输出,便于脚本提取产物
packer validate -syntax-only . && packer build .CI 标准两步:校验 + 构建
packer build -parallel-builds=1 .限制并发,避免云配额被打满
packer fmt -check -recursive .流水线格式门禁
sensitive 变量 + CI Secret 注入凭据不落仓库、不进日志
构建缓存:缓存插件目录与 ISO显著缩短流水线时长
命令 / 配置说明复制
Error: Unsupported argument参数名写错或插件版本不支持,对照插件文档
Unknown variable / Variables not allowed变量未定义或传参文件名写错
plugin not installed / could not find plugin未执行 packer init 或插件源不可达
failed to initialize build源码块必填项缺失,看后续具体字段提示
Error launching source instance: AuthFailure云凭据无效或权限不足
Timeout waiting for SSH网络不通、安全组未放通 22 端口或 ssh_username 错误
Permission denied (publickey)密钥未注入或用户名与镜像不匹配
Provisioner exited with a non-zero exit status脚本执行失败,看 PACKER_LOG 中的 stderr
docker: image not found镜像名/标签错误或私有仓库未登录
qemu: could not load PC BIOS缺少 OVMF/BIOS 文件或路径不对
checksum mismatch on ISOiso_checksum 与文件不匹配,重新下载或修正值
no space left on device构建机磁盘不足,清理缓存或扩大磁盘
ResourceNotReady / RequestLimitExceeded云资源未就绪或触发 API 限流,重试并降低并发
InvalidAMIID.NotFoundsource_ami 不存在或区域写错
构建成功但没有产物commit=false 或缺少 post-processor
旧 JSON 模板报 deprecated用 packer hcl2_upgrade 迁移到 HCL2

运维常用组合

本地首次构建packer init . → packer fmt . → packer validate . → packer build -debug . → 查看 manifest.json
CI 流水线packer init → packer fmt -check -recursive → packer validate → packer build -on-error=cleanup -machine-readable
多环境镜像common.pkrvars.hcl + prod.pkrvars.hcl → -var-file 叠加 → 镜像名带环境前缀 → manifest 归档
Docker 镜像发布source docker → provisioner shell → post-processor docker-tag → docker-push → manifest
云镜像上线data amazon-ami → source amazon-ebs → shell provisioner → build → manifest 取 AMI ID → 更新启动模板
排障路径PACKER_LOG=1 → -debug 单步 → -on-error=ask 保留现场 → 检查 provisioner stderr 与云控制台资源

常见问题排查

1. 先 init 再 validate

1.7+ 插件独立分发,未 init 时 validate 会因找不到插件失败

2. 镜像名带时间戳

用 {{timestamp}} 生成唯一名称,避免云上重名冲突

3. 基础镜像用 data 源

动态查询最新 AMI/镜像,避免硬编码导致长期不更新的老系统

4. provisioner 幂等可重跑

脚本要能在半成品镜像上重复执行,失败重试才不脏

5. 敏感值走 Secret

变量标 sensitive 并用 PKR_VAR_ 注入,禁止写进 pkrvars 提交仓库

6. 构建产物要留痕

manifest + checksum 让发布可追溯,比解析日志可靠

共 134 条 Packer 命令 · 示例中的镜像名、区域与路径请替换为实际环境

关于Packer命令速查

在线 HashiCorp Packer 命令速查手册,按安装与版本、初始化与插件、格式化与校验、构建 build、模板结构 HCL2、变量与传值、构建器 source、Provisioner 配置、Post-processor、Docker 与 QEMU 实战、调试与 CI 集成、常见报错与排查等 12 类场景整理 130+ 条常用命令与配置片段,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 packer version 与 PACKER_LOG/PACKER_LOG_PATH/PACKER_PLUGIN_PATH/CHECKPOINT_DISABLE 环境变量、packer init 与 -upgrade 与 plugins installed/required/install/remove 与 required_plugins 版本约束、fmt 的 -recursive/-check/-diff 与 validate 的 -syntax-only/-except/-var-file 与 hcl2_upgrade、build 的 -var/-var-file/-only/-except/-force/-debug/-on-error 的 abort/cleanup/ask/-parallel-builds/-timestamp-ui/-machine-readable、HCL2 模板的 packer/variable/locals/source/build/data 块与 {{timestamp}}/{{uuid}} 与 manifest post-processor、变量 PKR_VAR_ 与 *.auto.pkrvars.hcl 与 sensitive 与 validation 与优先级、source 的 amazon-ebs/amazon-ebssurrogate/googlecompute/azure-arm/docker/qemu/vmware-iso/virtualbox-iso/file/null、provisioner 的 shell 的 inline/script/scripts/environment_vars 与 file/shell-local/ansible/ansible-local/powershell/breakpoint/sleep 与 only/except、post-processor 的 manifest/docker-tag/docker-push/compress/checksum/vagrant/amazon-import/vsphere、Docker commit 与 changes 与 QEMU 的 iso_url/iso_checksum/boot_command/format/accelerator/qemuargs、packer console 与 -machine-readable 与 CI 两步校验与插件缓存,以及 Unsupported argument、Unknown variable、plugin not installed、failed to initialize build、AuthFailure、Timeout waiting for SSH、Permission denied publickey、Provisioner non-zero exit status、docker image not found、qemu could not load PC BIOS、checksum mismatch、ResourceNotReady、InvalidAMIID 等报错排查。适用于 Packer 镜像构建流水线、多云基础镜像统一制作、Docker 镜像规范化构建、Ansible/shell 自动化配置、镜像版本追溯与发布、构建性能与调试优化,以及 DevOps 与云原生运维面试复习。

核心能力

  • 涵盖 packer version 与 PACKER_LOG/PACKER_LOG_PATH/PACKER_PLUGIN_PATH/CHECKPOINT_DISABLE 环境变量、packer init 与 -upgrade 与 plugins installed/required/install/remove 与 required_plugins 版本约束、fmt 的 -recursive/-check/-diff 与 validate 的 -syntax-only/-except/-var-file 与 hcl2_upgrade、build 的 -var/-var-file/-only/-except/-force/-debug/-on-error 的 abort/cleanup/ask/-parallel-builds/-timestamp-ui/-machine-readable、HCL2 模板的 packer/variable/locals/source/build/data 块与 {{timestamp}}/{{uuid}} 与 manifest post-processor、变量 PKR_VAR_ 与 *.auto.pkrvars.hcl 与 sensitive 与 validation 与优先级、source 的 amazon-ebs/amazon-ebssurrogate/googlecompute/azure-arm/docker/qemu/vmware-iso/virtualbox-iso/file/null、provisioner 的 shell 的 inline/script/scripts/environment_vars 与 file/shell-local/ansible/ansible-local/powershell/breakpoint/sleep 与 only/except、post-processor 的 manifest/docker-tag/docker-push/compress/checksum/vagrant/amazon-import/vsphere、Docker commit 与 changes 与 QEMU 的 iso_url/iso_checksum/boot_command/format/accelerator/qemuargs、packer console 与 -machine-readable 与 CI 两步校验与插件缓存,以及 Unsupported argument、Unknown variable、plugin not installed、failed to initialize build、AuthFailure、Timeout waiting for SSH、Permission denied publickey、Provisioner non-zero exit status、docker image not found、qemu could not load PC BIOS、checksum mismatch、ResourceNotReady、InvalidAMIID 等报错排查

适用场景

适用于 Packer 镜像构建流水线、多云基础镜像统一制作、Docker 镜像规范化构建、Ansible/shell 自动化配置、镜像版本追溯与发布、构建性能与调试优化,以及 DevOps 与云原生运维面试复习。Packer命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Packer命令速查是免费的吗?需要注册或安装吗?
Packer命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Packer命令速查支持哪些功能?
涵盖 packer version 与 PACKER_LOG/PACKER_LOG_PATH/PACKER_PLUGIN_PATH/CHECKPOINT_DISABLE 环境变量、packer init 与 -upgrade 与 plugins installed/required/install/remove 与 required_plugins 版本约束、fmt 的 -recursive/-check/-diff 与 validate 的 -syntax-only/-except/-var-file 与 hcl2_upgrade、build 的 -var/-var-file/-only/-except/-force/-debug/-on-error 的 abort/cleanup/ask/-parallel-builds/-timestamp-ui/-machine-readable、HCL2 模板的 packer/variable/locals/source/build/data 块与 {{timestamp}}/{{uuid}} 与 manifest post-processor、变量 PKR_VAR_ 与 *.auto.pkrvars.hcl 与 sensitive 与 validation 与优先级、source 的 amazon-ebs/amazon-ebssurrogate/googlecompute/azure-arm/docker/qemu/vmware-iso/virtualbox-iso/file/null、provisioner 的 shell 的 inline/script/scripts/environment_vars 与 file/shell-local/ansible/ansible-local/powershell/breakpoint/sleep 与 only/except、post-processor 的 manifest/docker-tag/docker-push/compress/checksum/vagrant/amazon-import/vsphere、Docker commit 与 changes 与 QEMU 的 iso_url/iso_checksum/boot_command/format/accelerator/qemuargs、packer console 与 -machine-readable 与 CI 两步校验与插件缓存,以及 Unsupported argument、Unknown variable、plugin not installed、failed to initialize build、AuthFailure、Timeout waiting for SSH、Permission denied publickey、Provisioner non-zero exit status、docker image not found、qemu could not load PC BIOS、checksum mismatch、ResourceNotReady、InvalidAMIID 等报错排查。
Packer命令速查适合哪些场景使用?
适用于 Packer 镜像构建流水线、多云基础镜像统一制作、Docker 镜像规范化构建、Ansible/shell 自动化配置、镜像版本追溯与发布、构建性能与调试优化,以及 DevOps 与云原生运维面试复习。