5.5 使用 freebsd-update 更新 FreeBSD

freebsd-update 是 FreeBSD 官方提供的二进制更新工具，仅支持一级架构的 RELEASE、ALPHA、BETA、RC 版本，CURRENT 和 STABLE 不适用。

注意
只有一级架构的 ALPHA、BETA、RC、RELEASE 版本才提供该更新源。也就是说，CURRENT 和 STABLE 不适用。关于架构的支持等级说明请参见：FreeBSD Project. Supported Platforms[EB/OL]. [2026-03-26]. https://www.freebsd.org/platforms.

注意
ZFS 相关升级请参见 ZFS 章节。

5.5.1 历史

FreeBSD 提供了实用工具 freebsd-update，用于安装系统更新，包括升级到新的大版本。freebsd-update 最早随 FreeBSD 6.2-RELEASE 纳入基本系统，用于安全更新和勘误补丁；在 FreeBSD 6.3-RELEASE 中引入了 upgrade 命令，至 7.0-RELEASE 时正式成为官方支持的升级途径。

5.5.1.1 参考文献

FreeBSD Project. FreeBSD 6.2-RELEASE Release Notes[EB/OL]. [2026-04-16]. https://www.freebsd.org/releases/6.2R/relnotes.html. 发行说明，“The freebsd-update(8) utility is now included in the FreeBSD base system.”
FreeBSD Project. FreeBSD 7.0-RELEASE Announcement[EB/OL]. [2026-03-25]. https://www.freebsd.org/releases/7.0R/announce/. 官方公告明确 freebsd-update 为支持的二进制更新工具，适用于版本升级、安全修复及勘误补丁。
FreeBSD Project. freebsd-update -- fetch, install, and rollback FreeBSD updates[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=freebsd-update&sektion=8. FreeBSD 系统更新工具手册页。

5.5.2 将默认文本编辑器替换为更简单的编辑器

5.5.2.1 Bash、Zsh 或 sh

# export EDITOR=/usr/bin/ee  # 切换 vi 为 ee，默认为 nvi
# export VISUAL=/usr/bin/ee  # 切换 vi 为 ee

5.5.2.2 csh / tcsh

# setenv EDITOR /usr/bin/ee  # 切换 vi 为 ee，默认为 nvi
# setenv VISUAL /usr/bin/ee  # 切换 vi 为 ee

5.5.2.3 检查与验证

查看当前终端默认文本编辑器：

# echo $EDITOR
/usr/bin/ee

查看当前终端可视化文本编辑器：

# echo $VISUAL
/usr/bin/ee

5.5.3 常规补丁/安全更新（`X.Y-RELEASE` → `X.Y-RELEASE-pN`）

警告
无论是大版本更新、点版本更新还是常规更新，都应该先执行该流程。不可跳过，否则可能导致依赖缺失或系统无法正常启动。

5.5.3.1 FreeBSD 版本检查

# freebsd-version -kru
14.3-RELEASE
14.3-RELEASE
14.3-RELEASE

5.5.3.2 进行更新

获取更新

# freebsd-update fetch

当出现类似如下信息时：

usr/include/c++/v1/tr1/vector usr/include/c++/v1/tr1/version usr/include/c++/v1/tr1/wchar.h usr/include/c++/v1/tr1/wctype.h usr/include/c++/v1/unwind-arm.h
usr/include/c++/v1/unwind-itanium.h usr/include/c++/v1/unwind.h
usr/include/crypto/cryptodev.h usr/include/crypto/cbcmac.h usr/include/crypto/deflate.h usr/include/crypto/gfmult.h usr/include/crypto/gmac.h
usr/include/crypto/rijndael.h usr/include/crypto/rmd160.h usr/include/crypto/xform.h
usr/lib/clang/18.1.8/include
: q # 这里输入 q 再按回车键

上面列出的路径仅为示例输出，实际系统中的路径名称和数量可能会略有不同，请以实际输出为准。

此处列出的是发生变动的文件，确认后只需输入字母 q（代表“quit”，退出）并按回车键即可。

然后安装更新：

# freebsd-update install

若需自动化定期检查更新，可改用 freebsd-update cron，该命令会随机延迟 1 至 3600 秒后执行 fetch，并在有可用更新时发送邮件通知（收件人默认为 root，可通过 -t 指定）。PAGER 环境变量（默认 /usr/bin/less）控制合并报告的分页行为，设为 cat 可禁用交互式分页。

5.5.3.3 验证更新后的 FreeBSD 版本

查看更新后的 FreeBSD 版本：

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE
14.3-RELEASE-p6

注意
有时补丁不涉及内核，内核版本不会改变，用 uname -r 无法体现，但用户空间版本会发生变化。因此可能会看到两个版本号，应以较高者为准。

重启系统：

# reboot

查看 FreeBSD 版本：

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

5.5.4 大版本更迭（`X.Z-RELEASE-pN` → `A.0-RELEASE`）

注意
freebsd-update 下载慢不是因为其更新源在境外（使用境外服务器更新一样慢）。这可能与其设计缺陷有关，freebsd-update 是一个由数千行组成的纯 Shell 脚本。这是长期存在的问题。
freebsd-update upgrade 在工作目录（默认 /var/db/freebsd-update/）中可能需要最多 500 MB 空间，具体取决于已安装的基本系统组件。若升级因空间不足中断，可使用 -F 标志强制继续。

以 FreeBSD 14.3-RELEASE 升级到 15.0-RELEASE 为例

5.5.4.1 检查版本

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

警告
由于大版本间的变动可能影响 freebsd-update 更新工具本身，所以务必：
先更新到当前版本最新的补丁版本（如 X.Y-RELEASE-pN），然后再更新到最新的点版本（如 X.Z-RELEASE）。
接下来，更新到最新的点版本及该点版本上最新的补丁版本（如 X.Z-RELEASE-pN）
最后：完成大版本（X.Z-RELEASE-pN——>A.0-RELEASE）的更迭。
参见：libsys.so.7 not found when upgrading userland with legacy freebsd-update[EB/OL]. [2026-03-26]. https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=289769。

5.5.4.2 更新到 15.0-RELEASE

升级系统到 FreeBSD 15.0-RELEASE 版本：

# freebsd-update upgrade -r 15.0-RELEASE

……当出现类似于下列信息时，按照下方提示操作……

src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching metadata signature for 14.3-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata patches.. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/generic kernel/generic-dbg world/base world/lib32

The following components of FreeBSD do not seem to be installed:
world/base-dbg world/lib32-dbg

Does this look reasonable (y/n)? y # 在这里输入 y，然后回车即可，此处是在检查基本组件的安装情况。

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system...

…………此处是在检查系统，从上面的回车到这里需要等待约 10 分钟…………

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.
Fetching files from 14.3-RELEASE for merging... done.
Preparing to download files... done.

…………此处是在准备要下载的文件，需要等待约 15 分钟…………

Fetching 6735 patches.....10....20....30....40....50....60....70....80....90.

………………下面需要等待约 30 分钟。注意，跨大版本更新时，有时需要等待 5 小时或更长时间，这都属于正常现象。………………

....100....110....120....130....140....150....160....170....180....190....200

…………中间省略………………

20....6630....6640....6650....6660....6670....6680....6690....6700....6710....6720....6730.. done.
Applying patches...

………………打补丁，需要等待约 5 分钟………………

Applying patches... done.
Fetching 880 files... ....10....20....30....4

………………省略一部分进度条………………

0....880 done.
Attempting to automatically merge changes in files... done.

The following file could not be merged automatically: /etc/pkg/FreeBSD.conf
Press Enter to edit this file in /usr/bin/ee and resolve the conflicts
manually...

……这里提示按回车键编辑无法自动合并而需手动处理的文件……

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/login.conf:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

 #site:\
-#      :ignoretime:\
 #      :passwordtime@:\
 #      :refreshtime@:\
 #      :refreshperiod@:\
 #      :sessionlimit@:\
 #      :autodelete@:\
Does this look reasonable (y/n)? # 输入 y 回车，此处是在确认系统文件的变动

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/pkg/FreeBSD.conf:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

Does this look reasonable (y/n)?  # 输入 y 回车，此处是在确认系统文件的变动

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/ssh/sshd_config:
--- current version
+++ new version

……此处列出的是发生变动的文件，省略一部分输出……

 # override default of no subsystems
Does this look reasonable (y/n)? # 输入 y 回车，此处是在确认系统文件的变动

The following files are affected by updates. No changes have
been downloaded, however, because the files have been modified
locally:
/etc/ssl/cert.pem
(END) # 这里是发生变动的文件，确认后只需输入字母 q（代表“quit”，退出）再按回车键即可。

# 上面列出的路径仅为示例输出，实际系统中的路径名称和数量可能会略有不同，以本机实际显示为准。

The following files will be removed as part of updating to
15.0-RELEASE-p0:
/.cshrc
/.profile
/boot/kernel/callout_test.ko
/boot/kernel/geom_bde.ko
/boot/kernel/geom_vinum.ko

…………中间省略，这些是将删除的文件………………

/usr/share/examples/sound/sndstat_nv.c
: # 这里输入 q，确认变动，直至没有新内容出现

…………中间省略………………

The following files will be added as part of updating to
15.0-RELEASE-p0:
/boot/firmware/iwm3160fw
/boot/firmware/iwm3168fw
/boot/firmware/iwm7260f

…………中间省略这些是新增的文件………………

/boot/kernel/nvmf_tcp.ko
/boot/kernel/nvmf_transport.ko
/boot/kernel/nvmft.ko
/boot/kernel/p9fs.ko
: # 这里输入 q，确认变动，直至没有新内容出现

The following files will be updated as part of updating to
15.0-RELEASE-p0:
/COPYRIGHT
/bin/[
/bin/cat

…………中间省略这些是更新的文件………………

/bin/kenv
/bin/kill
/bin/link
/bin/ln
/bin/ls
/bin/mkdir
/bin/mv
/bin/nproc
To install the downloaded upgrades, run 'freebsd-update [options] install'.

运行 freebsd-update install 以安装更新：

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Kernel updates have been installed.  Please reboot and run
'freebsd-update [options] install' again to finish installing updates.

内核更新已安装：

# freebsd-version -kru
15.0-RELEASE
14.3-RELEASE-p5
14.3-RELEASE-p6

可以看到，当前已安装内核的版本和补丁级别是 15.0-RELEASE。但用户空间和当前正在运行的系统仍是 14.3-RELEASE，因此需要按照 freebsd-update 的提示重启：

# reboot

运行 freebsd-update install 安装用户空间的更新部分：

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Restarting sshd after upgrade
Performing sanity check on sshd configuration.
Stopping sshd.
Waiting for PIDS: 906.
Performing sanity check on sshd configuration.
Starting sshd.

Completing this upgrade requires removing old shared object files.
Please rebuild all installed 3rd party software (e.g., programs
installed from the ports tree) and then run
'freebsd-update [options] install' again to finish installing updates.

重新安装 pkg 本身，将 ABI 更新到 15.0-RELEASE：

# pkg bootstrap -f
The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y # 此处输入 y 后回车
Bootstrapping pkg from pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
Installing pkg-2.4.2...
package pkg is already installed, forced install
Extracting pkg-2.4.2: 100%

将第三方程序的 ABI 更新到 15.0-RELEASE：

# pkg upgrade
Updating nju repository catalogue...
Fetching meta.conf:   0%
Fetching data.pkg: 100%    7 MiB   7.6MB/s    00:01
Processing entries: 100%
nju repository update completed. 35765 packages processed.
All repositories are up to date.
Updating database digests format: 100%
Checking for upgrades (215 candidates): 100%
Processing candidates (215 candidates): 100%
The following 223 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
	ceres-solver: 2.2.0_10

…………中间省略………………

The process will require 45 MiB more space.
687 MiB to be downloaded.

Proceed with this action? [y/N]:  # 此处输入 y 再回车即可

…………中间省略………………

Proceed with this action? [y/N]:  # 此处输入 y 再回车即可，可能会出现多次，下同

第三方程序的更新至此完成。

再次执行 freebsd-update 以完成更新流程。

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates... done.

验证操作系统版本：

# freebsd-version -kru
15.0-RELEASE
15.0-RELEASE
15.0-RELEASE

系统更新完成。

5.5.5 故障排除与未竟事宜

5.5.5.1 回滚更新

回滚最近一次系统更新：

# freebsd-update rollback

5.5.5.2 pkg 找不到 `.so` 文件

终端执行命令强制初始化 pkg 包管理器：

# pkg bootstrap -f

5.5.5.3 FreeBSD 升级出错，导致缺少 ntpd 用户

终端执行命令：

# pw groupadd ntpd -g 123  # 创建 ntpd 用户组，GID 为 123
# pw useradd ntpd -u 123 -g ntpd -h - -d /var/db/ntp -s /usr/sbin/nologin -c "NTP Daemon"  # 创建 ntpd 用户，UID 为 123，主目录 /var/db/ntp，禁止登录，仅用于 NTP 守护进程

5.5.6 课后习题

阅读 freebsd-update 脚本的源代码，使用高级编程语言重构，并验证是否能显著提升更新速度。
制作一个 freebsd-update 镜像站。
freebsd-update 的二进制补丁模型依赖于对基本系统组件版本的精确跟踪，而第三方软件的更新则交由 pkg 管理。分析这种“基本系统与 Ports 分离”的更新策略在 ABI（Application Binary Interface）兼容性保障方面的优势，及其对滚动更新需求造成的限制。

5.5 使用 freebsd-update 更新 FreeBSD ​

5.5.1 历史 ​

5.5.1.1 参考文献 ​

5.5.2 将默认文本编辑器替换为更简单的编辑器 ​

5.5.2.1 Bash、Zsh 或 sh ​

5.5.2.2 csh / tcsh ​

5.5.2.3 检查与验证 ​

5.5.3 常规补丁/安全更新（X.Y-RELEASE → X.Y-RELEASE-pN） ​

5.5.3.1 FreeBSD 版本检查 ​

5.5.3.2 进行更新 ​

5.5.3.3 验证更新后的 FreeBSD 版本 ​

5.5.4 大版本更迭（X.Z-RELEASE-pN → A.0-RELEASE） ​

5.5.4.1 检查版本 ​

5.5.4.2 更新到 15.0-RELEASE ​

5.5.5 故障排除与未竟事宜 ​

5.5.5.1 回滚更新 ​

5.5.5.2 pkg 找不到 .so 文件 ​

5.5.5.3 FreeBSD 升级出错，导致缺少 ntpd 用户 ​

5.5.6 课后习题 ​