Gen AI 时代，抗拒AI是愚蠢的，滥用AI是可耻的。为了规范AI使用边界，本博客中的文章可能标有如下标签：

• AI-ASSISTED：本文间接包含AI生成内容作为人工写作的参考，如果存在错误则即使不用AI博主也会在这里犯错（说不定错的更离谱），可放心食用；
• AI-REFINED：本文为博主完成草稿后全篇由AI润色的产物，除博主能力所限外还可能存在LLM幻觉导致的错误和文风一股入机味，但应该无伤大雅~
• MAN-MADE：本文为博主纯手搓；
• 目前没有直接包含AI生成内容的计划——想看这种东西为什么不直接把想看的当提示词发给AI让它生成呢？

博主郑重承诺：我们不制造电子垃圾，任何标签均为如实声明

环境变量是什么

环境变量（Environment Variable）：操作系统提供给进程的键值对。进程启动时继承父进程的整个环境，可用于配置程序行为、传递路径信息等。常见如 HOME、USER、SHELL、LANG。

PATH：最核心的环境变量，告诉 Shell 在哪些目录中按顺序搜索可执行文件。敲一条命令时，Shell 挨个扫 PATH 里的目录——先找到的就执行，后面的不再查。

动态库搜索路径：程序运行时查找共享库（Linux .so、macOS .dylib、Windows .dll）的机制。逻辑与 PATH 类似但机制因平台差异极大，是最容易踩跨平台坑的领域。

我什么时候会用到它

抛开应用程序主动用它传配置不谈，最常用的场景就是手动安装命令行工具。处于某些原因我们不想用包管理器或安装器安装程序时（它们通常会帮你配置好环境变量）而是直接下载一个压缩包的可执行文件使用时，我们要告诉 Shell 在哪里找到我们下载的可执行文件，即配置环境。通常情况下，只需要将可执行文件所在的目录添加到 PATH 环境变量里即可。那么，怎么添加？——

怎么读

环境变量的读取范围分四层，搞不清这个是"设了但不生效"的第一大原因：

同名变量在多层设置时，层级越窄优先级越高： 进程级 > Shell级 > 用户级 > 系统级）

这里的行为，与其说是平台特定，不如说是 Shell 特定：比如，如果你在 Windows 上用 Bash，那其实更应该参考 Linux 的设置。

为什么写文件可以修改环境变量？这是 Shell 的设计机制：Shell 启动时会按一定规则运行特定的初始化脚本，而作为所有命令的入口，所有的 Shell 都设置了的环境，相当于就是整个用户/系统的环境。

特例：

• Linux /etc/environment 是用户登录时由 PAM 读取的，格式为 KEY=VALUE
• macOS /etc/paths 只管 $PATH，每行一个路径，不是 KEY=VALUE 格式；/etc/paths.d/* 同理（每个文件一行一个路径）

Shell 的 Login / Non-login——Linux/macOS 最大的坑

Shell 启动方式决定它读取哪些配置文件，这直接决定你的环境变量在哪个文件里写才能生效：

bash 读取顺序

bash 的 Login Shell 优先级列表 ~/.bash_profile > ~/.bash_login > ~/.profile 诞生于 Unix 历史的“兼容期”，它是为了解决多流派 Shell 用户的迁移问题，而非让你把三个文件都用上。

1. ~/.profile 是 Bourne Shell (sh) 的老祖宗标准： 在当年，所有 Unix 系统的默认 Shell 都是 sh，大家都把环境变量写在 ~/.profile 里。直到今天，如果你用的是 Ubuntu，它的底层系统默认 Shell 是 dash，dash 启动时依然只认 ~/.profile。
2. ~/.bash_login 是对 C Shell (csh) 的妥协：当年有一大批写 ~/.login 的 csh 用户转投 Bash，为了照顾他们的习惯，Bash 加了这个支持。
3. ~/.bash_profile 是 Bash 的“亲儿子”：Bash 诞生增加了很多 sh 不支持的高级语法（比如数组、特殊的字符串处理）。如果用户把这些高级语法写进 ~/.profile，当系统其他组件用 sh 或 dash 读取这个文件时，就会直接报错。

为什么设计为互斥隔离（只读找到的第一个）？ 如果 Bash 依次把这三个全读一遍，往往会引发灾难（比如环境变量 PATH=...:$PATH 被重复追加三次、打印了三次登录欢迎语、或者因为语法不兼容报错）。在 Bash 开发者的视角里：

如果你写了专属的 .bash_profile，我就按你的来；如果你没写，我就去看你是不是习惯用 .bash_login；如果你连这都没写，那我就去读最普通的 .profile 保底。千万别读两次。

但这导致了一个巨大的痛点：用户必须在 login 和 non-login 两个文件里维护两套配置。为了解决这个问题，现代的 Linux 发行版（如 Ubuntu, CentOS, Debian）在默认给用户生成家目录（从 /etc/skel/ 拷贝）时，动了一个非常聪明的“手脚”——强制桥接。现代发行版真实的 Login Shell 读取顺序变成了一个嵌套链条：

1. bash 加载 /etc/profile -> 遍历并 source /etc/profile.d/*.sh （用于配置系统级环境变量）和去读 /etc/bash.bashrc
2. bash 去找并读取 (~/.bash_profile > ~/.bash_login > ~/.profile) -> 去读 ~/.bashrc

然而，想象如下情景：

1. 系统默认只有 ~/.profile（里面包含了调用 bashrc 的桥接代码）。
2. 你为了配置环境变量，上网随便搜了一篇教程，自己新建了一个 ~/.bash_profile 文件并在里面写了 export PATH=...。
3. 灾难发生：由于 Bash 的优先级是 ~/.bash_profile > ~/.profile，你的 Login Shell 发现了你新建的文件，就不会再去读系统的 ~/.profile 了。
4. 结果：你新建的文件里没有那段“桥接代码”，导致你的 ~/.bashrc 彻底被 Login Shell 抛弃，以前在 bashrc 里配的所有别名（alias）和变量在 SSH 登录时全部失效。

因此，上网查教程时要特别小心，尤其是你发现它在用>>（流追加符）这种看似无害的东西修改配置文件时，因为你永远不知道它究竟是简单的追加还是默默新建了一个优先级更高的配置。

zsh 读取顺序（macOS Catalina+ 默认）

zsh 无论是否 login，都读 ~/.zshrc，所以 zsh 下环境变量只需放在 ~/.zshrc 就够了——比 bash 简单得多。

怎么写

Windows

Windows GUI 程序改完环境变量后不会自动感知，需要重启该程序。虽然系统会广播 WM_SETTINGCHANGE 消息，但很多程序忽略此消息。可能可以通过重启程序或重新登录生效，但既然都是 Windows 了，最可靠的方式还是重启系统。

Linux

为什么有 /etc/profile 还要 /etc/profile.d/？

系统包更新可能覆盖 /etc/profile ，但 /etc/profile.d/ 下的文件独立存在不受影响。/etc/ 下很多配置其实都有 xxx 和 xxx.d/ ——以便分离默认配置和用户配置。

GUI 应用（从桌面环境启动的）不读 ~/.bashrc。

它们的进程由 display manager (如 GDM) 创建，继承的是 systemd 用户会话环境。给 GUI 应用设环境变量的正确方式：

# ~/.config/environment.d/my-vars.conf  (systemd 用户环境)
JAVA_HOME=/usr/lib/jvm/java-11
PATH=/home/you/.local/bin:${PATH}

此目录下的 .conf 文件格式同 /etc/environment（纯 KEY=VALUE），由 systemd-user 启动时读取，仅对 GUI 应用生效。

macOS

macOS Catalina (10.15) 起默认 Shell 从 bash 改为 zsh。

旧版升级后，~/.bash_profile 里的配置在新终端中完全不生效。迁移：把 bash 配置搬到 ~/.zprofile（login 级）+ ~/.zshrc（interactive 级）。

macOS 的 PATH 机制独特。

不在 /etc/environment 里（此文件不存在），而是用 /etc/paths + /etc/paths.d/。加系统级 PATH 目录的正确做法：

# 加一个文件到 /etc/paths.d/
sudo tee /etc/paths.d/homebrew <<EOF
/opt/homebrew/bin
EOF

注意这里用 tee 而非流重定向符，是因为 sudo 只管命令运行权限，而流是由 Shell 处理的——用 sudo 不就是因为 Shell 权限不够嘛。你要用 sudo sh -c 'echo /opt/homebrew/bin >> /etc/paths.d/homebrew' 也是一样的。

GUI 应用（从 Dock/Launchpad 启动）不继承 Shell 环境变量。

macOS 的 GUI 应用由 launchd 启动，launchd 的环境来自系统级配置，不读 ~/.zshrc。给 GUI 应用设环境变量的正确方式：

launchctl setenv KEY value
launchctl unsetenv KEY

PATH 设置最佳实践

各平台追加 PATH 的安全写法

# Linux/macOS — 在 ~/.bashrc 或 ~/.zshrc 中
export PATH="$HOME/.local/bin:$PATH"    # 前置（优先使用个人版本）
export PATH="$PATH:/opt/some-tool/bin"  # 后置（系统版本优先，仅补充）

# Windows PowerShell — 用户级永久追加
[Environment]::SetEnvironmentVariable(
    "PATH",
    [Environment]::GetEnvironmentVariable("PATH", "User") + ";C:\Tools\Bin",
    "User"
)

动态库搜索——跨平台差异最大的领域

三平台机制速览

Windows DLL 搜索顺序

Windows 的 PATH 同时管可执行文件搜索和 DLL 搜索.

这是独一无二的：PATH 里加个目录，不光影响命令查找，还影响 DLL 加载。PATH 越宽，DLL 搜索范围也越宽，可能加载到错误版本 DLL（DLL Hell 的根源）。这也是为什么 Windows 下按个 Tab 会冒出来一堆不能直接运行的.dll.

SafeDllSearchMode 开启时（Windows Vista+ 默认）：

SafeDllSearchMode 关闭时（仅旧系统），当前目录排在 PATH 前面——这是安全隐患。

最佳实践：DLL 放在应用程序自己的目录下——这是搜索顺序第一位，最可靠且不影响其他程序。尽量不要依赖 PATH 来找 DLL。 这也就是为什么 Windows 下 FFmpeg 那么容易出问题：FFmpeg 的协议使其经常没法再分发，只能手动补齐。

Linux 动态库搜索

搜索顺序：

设置方法：

LD_LIBRARY_PATH 应当只临时使用。

LD_LIBRARY_PATH 不应永久写入 Shell 配置。它会覆盖 ldconfig 缓存和默认路径，可能导致系统工具加载到错误版本的库（比如你的 LD_LIBRARY_PATH 里有个旧版 libssl，系统 curl 就可能加载它然后崩掉）。

RPATH vs RUNPATH 行为不同。

RPATH 在 LD_LIBRARY_PATH 之前搜索（可被 RPATH 覆盖），RUNPATH 在之后搜索（LDLIBRARYPATH 可覆盖 RUNPATH）。现代 binutils 默认用 RUNPATH。如果你需要编译时路径覆盖环境变量，要显式用 -Wl,--disable-new-dtags（强制 RPATH）——但这通常不是你想要的。

$ORIGIN 是一个特殊的 rpath 值，展开为可执行文件所在目录。

用于可移植部署（可执行文件和库放同一目录树），但 $ORIGIN 必须写进 rpath 字面量，不能在 Shell 里展开——gcc 命令中要写成：

gcc -Wl,-rpath,'$ORIGIN/lib'  main.c  # 单引号保护 $ORIGIN 不被 Shell 展开

macOS 动态库搜索

搜索顺序：

macOS 的 @ 路径魔术——这是理解 macOS 动态库的关键：

macOS 的设计哲学：库的搜索路径编译进库本身（install name），而不是依赖环境变量。库的 install name 通常形如 @rpath/libfoo.dylib，加载时 dyld 用主程序的 rpath 列表展开 @rpath 为具体目录。

设置方法：

Homebrew 安装的库使用绝对路径 install name（/opt/homebrew/lib/libfoo.dylib 或 /usr/local/lib/libfoo.dylib），Homebrew 在编译时通过 -rpath 让可执行文件能找到它们。如果你手动编译程序链接 Homebrew 库，必须传：

gcc -L/opt/homebrew/lib -Wl,-rpath,/opt/homebrew/lib main.c -lfoo

漏了 -rpath 就能编译但运行时找不到库——这是 macOS 上 dyld: Library not loaded 报错的第一大原因。

install_name_tool 是 macOS 独有的神器：

可以修改已编译 .dylib 的 install name 和已编译可执行文件的 rpath，不需要重新编译：

# 修改库声明自己的路径
install_name_tool -id @rpath/libfoo.dylib libfoo.dylib

# 修改可执行文件中对某库的引用路径
install_name_tool -change /old/path/libfoo.dylib @rpath/libfoo.dylib myapp

# 给可执行文件追加 rpath
install_name_tool -add_rpath /opt/homebrew/lib myapp

经验交流：每个平台的环境和动态库问题都有大量隐坑，尤其是 Windows 的 DLL 搜索顺序和 macOS 的 install name 体系——如果你有踩坑经验或补充，欢迎评论区分享。

是什么

本系列博文旨在解决就事论事解决问题不全面系统，翻书查教程冗长且可能过时的痛点，将凝练的知识系统性地组织起来，供入门用户建立认知框架，高级用户预知经验坑点。

为什么

博主深受其害：

• 碎片化搜答案：一个自以为是特例的报错，翻了半天社区讨论终于修好了，长舒一口气顺手清了浏览历史，结果没过几天同方向的问题又出现了，本可以复用的基础搜索又得全部重来；
• 硬啃完整教程：想用个项目，结果单开一个网页的 Wiki / Documention 翻半天找不到要用的点，回 GitHub 文档仓库一搜发现压根没写，定睛一看原来维护者在 issue 里说 not-planned

对于低频场景，稍微花点时间跳读一下可能无伤大雅；但当连自己都注意到了经常在做无用功，那不妨跟我一起总结经验教训。

怎么办

• 聚焦坑点：不再把坑点当补充，而是作为正文主要部分
• 标记时间：博文自带最后修改时间标记，可能过时的提醒你谨慎阅读

适合谁

适合：

• 速查的高级用户：直接翻目录或 Ctrl+F，找你要的那节，参数表格和命令示例都在
• 想系统了解的小白：从头读，每个参数都有解释

不适合：

• 想看保姆式教程的人：场景千变万化，要全列出来这就不是速查表了；但根因殊途同归，本系列博文尽管没法告诉你怎么做但至少尽可能教会你为什么；

• 只想要不二法门的人：授人以鱼不如授人以渔，适合的才是最好的，天天看杠精叫嚣“诶你这个通用解决方案不如我在我自己特定场景下调整过的在我自己的特定场景下的表现更好”有意思吗？与其给你个大多数时候够用的通用解决方案，不如教会你怎么针对自己的特定场景优化。

说在最后

作为经验交流，博主个人的经验总是有限的，在这里也鼓励大家在评论区讨论分享自己的经验之谈。

谁应该看这篇文章？

适合：

• 速查的高级用户：直接翻目录或 Ctrl+F，找你要的那节，参数表格和命令示例都在
• 想系统了解的小白：从头读，每个参数都有解释，假定你不熟悉命令行

不适合：

• 想抬杠的：关于哪种编码器在哪种内容下 VMAF 更高，这个问题没有金标准。根据信息论的基本原理，不可能存在一种编码既无损画质又极低码率——一切都是 trade-off，只能对特定视频源做 VMAF 实测才能得出有效结论。如果你热衷这类深度分析，出门左转这篇文章更适合你：视频压缩深度测试（知乎）

• 只盯着存储成本的人：除了存储成本，还有——编码时间成本（压个视频让电脑满载几百个小时值不值）、解码平台限制成本（目标设备不支持AV1还得转回来再看）、编解码电费成本（显卡满载的功耗感人）、调参时间成本（每种不同的视频源都得反复测 VMAF 和调参）。存储是成本，这些也是成本，甚至还有你看这篇文章本身的时间成本，都应该考虑在内。

为什么用 FFmpeg CLI，而不是 GUI 工具？

市面上有很多 GUI 封装工具——小丸、格式工厂、ShanaEncoder、HandBrake、FFmpegFreeUI 等等，它们的本质大多是给 FFmpeg 套了个图形界面，把你在界面里选的参数翻译成 FFmpeg 命令在后台运行。尽管并非所有 GUI 工具都基于 FFmpeg（例如 HandBrake 部分功能直接调用显卡厂商 SDK），但功能上大差不差。

GUI 工具的问题：

• 参数覆盖不全：GUI 不可能把 FFmpeg 所有参数都列出来，总有你需要但界面没有的选项
• 停更风险与沉没成本：很多小工具停更了你就傻了，学会的操作逻辑也迁移不走；FFmpeg 本身几乎不可能停更，它已经是音视频处理领域的基础设施级的存在了，掌握了就是你的
• 自由度受限：脚本化、批量处理、条件判断，CLI 天然支持，GUI 永远差一口气

并不是说 GUI 工具不好，它们的确很方便（我自己也经常用 LosslessCut）；但掌握 FFmpeg CLI 之后，GUI 工具对你来说就指是"便利品"，而不是"必需品"，你永远有托底的杀手锏。

安装 FFmpeg

请直接参考官方指南 Download FFmpeg

如果用包管理器装，环境变量应该会自动配好，直接运行 ffmpeg 就可以；如果直接下载静态构建手动安装，记得手动添加环境变量或把命令中的 ffmpeg 改成相应路径。

验证安装： 打开终端或命令提示符，输入 ffmpeg -version，能看到版本信息就成功了。

一、基础概念

在输参数之前，有几个概念必须搞清楚。

1.1 容器格式 vs 编码格式

我们平时说的"MP4 文件"，严格来说由两层组成：

• 容器格式（封装格式）：文件的"外壳"，即文件扩展名所代表的格式。常见的有 .mp4、.mkv、.mov。容器负责把视频流、音频流、字幕流"装在一起"
• 编码格式：视频流本身的压缩标准。同样是 .mp4 容器，里面的视频流可能是 H.264，也可能是 H.265，或者 AV1

"这是个 MP4"只说明了容器，没说明编码。用 ffprobe（FFmpeg 三件套之一，和 ffplay 一样应该会一起装好）可以直接查看文件的元信息。

1.2 编码格式与编码器

编码格式只是标准，编码器才是执行者（按照标准把视频数据实际编码出来）。

常用对照表：

带 lib 前缀的是纯软件编码器（用 CPU 计算），其余为硬件编码器（调用显卡内专用编解码单元）。

关于显卡编码速度的常见误解：显卡的"3D 游戏性能"与视频编码速度几乎无关。NVIDIA 的 NVENC 编码单元是独立的专用硬件——4060 和 4090 在单个编码任务上速度基本一致，因为两者都只有一两个 NVENC 单元，是 NVENC 单元数量和代际决定速度，而不是 CUDA 核心数量。

1.3 码率（比特率）

码率 = 视频每秒传输的数据量，单位是 kbps（千比特/秒）或 Mbps（兆比特/秒）。

• 1080p 普通内容（教程、生活录像）：1-3 Mbps 通常够用
• 1080p 高动态游戏录屏：3-6 Mbps
• 4K 内容：8-20 Mbps

1.4 像素格式

• yuv420p：8bit，兼容性最广，几乎所有设备都支持
• yuv420p10le：10bit，色彩过渡更细腻，低码率下反而质量可能更好（不平滑的色彩过渡本身就是高频噪声会浪费码率），用 HEVC/AV1 且设备兼容时推荐

二、命令行基础语法

2.1 命令的基本结构

ffmpeg -i 输入文件.mp4 [各种参数] 输出文件.mp4

• ffmpeg：调用 FFmpeg 程序
• -i：input 的缩写，指定输入文件，后面跟文件路径
• 各种参数：每个选项都是 -参数名 参数值 的格式
• 最后一个路径（没有 - 开头的参数在前）通常是输出文件

2.2 反斜杠换行（bash / PowerShell）

ffmpeg -i 输入.mp4 \
  -c:v hevc_nvenc \
  -c:a copy     \
  输出.mp4

行末的 \ 表示"这行还没写完，下一行是接续"。这只是为了让很长的命令看起来更清晰，效果完全等同于写成一行。

Windows CMD 中不能用 ` 换行，要用 ^；Powershell 要用 ``，且前面要由空格；本文示例统一用 bash 格式，Windows 用户请自行替换，或者不换行直接写成一行。

2.3 环境变量

# bash 写法（Linux / macOS / Git Bash）
export VIDEO="https://example.com/video.mp4?sign=abc123xyz"
ffmpeg -i "$VIDEO" 输出.mp4

# PowerShell 写法
$VIDEO = "https://example.com/video.mp4?sign=abc123xyz"
ffmpeg -i "$VIDEO" 输出.mp4

export VIDEO="..." 是 bash 中设置变量的写法。之后用 $VIDEO，shell 会自动把它替换成那段 URL，避免重复输入。这个变量只在当前终端窗口的会话中有效，关闭窗口就消失了。

2.4 指定使用哪块 GPU

CUDA_VISIBLE_DEVICES=1 ffmpeg -i 输入.mp4 -c:v hevc_nvenc 输出.mp4

CUDA_VISIBLE_DEVICES=1 是一个临时环境变量，写在命令前，只对这条命令生效。它告诉 CUDA 只把编号为 1 的 GPU（编号从 0 开始）暴露给这个进程，FFmpeg 就只能用那块显卡。多卡机器分配任务时使用。

三、最基础的输入输出

3.1 查看文件信息

ffprobe 文件.mp4

FFProbe 会打印输入文件的元信息（分辨率、帧率、编码格式、时长、码率等），然后退出。这是快速查看文件信息的常用方式。

3.2 直接转封装（不重新编码）

ffmpeg -i 输入.mkv -c copy 输出.mp4

• -c：codec，指定编码器
• copy：对该流直接复制（不重编码）
• 速度极快，因为只是换了个容器"壳"，但仅适用于目标容器兼容源编码的情形，否则会报错。

3.3 覆盖已有文件

ffmpeg -i 输入.mp4 -c:v hevc_nvenc -c:a copy -y 输出.mp4

• -y：如果输出文件已存在，直接覆盖，不交互询问。不加这个参数时，FFmpeg 会停下来问你要不要覆盖

3.4 指定编码器

ffmpeg -i 输入.mp4 -c:v hevc_nvenc -c:a copy 输出.mp4

• -c：codec，指定编码器
• :v：video，对视频
• :a：audio，对音频
• copy：对该流直接复制（不重编码）

3.5 指定码率

ffmpeg -i 输入.mp4 -c:v hevc_nvenc -b:v 2M -c:a copy 输出.mp4

• -b：bitrate，指定码率
• 2M: 2Mbps，M 大写

四、时间裁剪与剪切

这是高频操作，和编码参数无关，单独讲清楚。

4.1 时间参数说明

-to 和 -t 的区别：-ss 30 -to 120 等于 -ss 30 -t 90，结果一样（从 30s 到 120s，共 90s），但逻辑语义不同，按需选用。

4.2 关键帧剪切（快，不精确）

ffmpeg -ss 30 -i 输入.mp4 -to 90 -c copy 输出.mp4

-ss 放在 -i 前面：FFmpeg 先快速 seek 到靠近 30s 的关键帧，然后再开始解码。由于关键帧不一定恰好在 30s，实际起点可能略早几秒。

-c copy 直接复制流，不重新编码，速度接近瞬间完成，适合快速提取片段。

4.3 重编码剪切（精确，较慢）

ffmpeg -i 输入.mp4 -ss 30 -to 120 -c:v hevc_nvenc -c:a aac 输出.mp4

-ss 放在 -i 后面：FFmpeg 从头解码，精确丢弃前 30s，起点精确到帧。代价是需要重新编码，速度相应变慢。

适合场景：本身就要重压缩的任务（剪切和二压合并成一步，不需要先切再压）。

建议：如果本来就要二压，直接用 -ss（放 -i 后）同时做剪切和压缩，一步到位。如果只是想快速切片段留着，用 -c copy，秒出结果，精度够用就行。

五、视频参数

5.1 分辨率缩放

ffmpeg -i 输入.mp4 -vf "scale=-2:1080" 输出.mp4

• -vf：video filter，视频滤镜，后面跟引号包裹的滤镜表达式
• scale=-2:1080：缩放滤镜
  • 第一个值 -2：宽度自动计算，保持原始宽高比，且结果能被 2 整除（编码器要求）
  • 第二个值 1080：目标高度 1080 像素
  • 写 scale=1920:1080 则强制指定宽和高（不保证宽高比）
  • 写 scale=1280:-2 则固定宽，高度自动算

5.2 帧率

ffmpeg -i 输入.mp4 -r 30 输出.mp4

• -r：设置输出帧率（Frames Per Second）。不加 -r 则保持输入帧率

5.3 像素格式

ffmpeg -i 输入.mp4 -pix_fmt yuv420p10le 输出.mp4

• -pix_fmt：pixel format
  • yuv420p：8bit，兼容性最好，保守推荐
  • yuv420p10le：10bit，HEVC/AV1 推荐

六、音频参数

6.1 直接复制音频（最推荐）

-c:a copy

源文件音频质量没问题的情况下，优先复制，无质量损失，而且快。

6.2 重新编码音频

ffmpeg -i 输入.mp4 -c:a aac -b:a 128k 输出.mp4

• -b:a 128k：音频目标比特率 128 kbps

常用音频编码器：

6.3 选择特定音轨

ffmpeg -i 输入.mkv -map 0:v:0 -map 0:a:1 -c copy 输出.mp4

• -map：手动指定要输出哪条流
  • 0：第 1 个输入文件（从 0 计数）
  • v:0：该文件的第 1 条视频流
  • a:1：该文件的第 2 条音频流（比如日语音轨）
• 不加 -map 时，FFmpeg 自动选每种类型中"最佳"的一条

七、码率控制模式

这是视频编码最核心的部分，直接决定画质和文件大小。

7.1 CRF 模式（CPU 编码器专用）

ffmpeg -i 输入.mp4 -c:v libx265 -crf 24 -c:a copy 输出.mp4

• -crf：Constant Rate Factor，恒定质量因子
• 数值越小画质越好文件越大，越大越糊越小
• 推荐范围：

重要：CRF 是 CPU 软件编码器专用，GPU 硬件编码器不支持 -crf。

7.2 CQ 模式（NVENC 的恒定质量）

ffmpeg -i 输入.mp4 -c:v hevc_nvenc -rc:v vbr -cq:v 28 -b:v 0 -c:a copy 输出.mp4

• -rc:v vbr：rate control，码率控制模式，vbr 是可变码率
• -cq:v 28：NVENC 的恒定质量值（类似 CRF，但数值对应关系不同）
• -b:v 0：目标码率设为 0，配合 CQ 使用，表示不额外限制码率

CQ 与 CRF 的对应关系（近似）：

libx264 -crf 24  ≈  h264_nvenc   -cq 28~30
libx265 -crf 24  ≈  hevc_nvenc   -cq 28~30
libsvtav1 -crf 34 ≈ av1_nvenc    -cq 34~36

⚠️ 最常见的误区：根据 CPU 编码 -crf 24 的经验，在用 GPU 编码时也选 -cq 24。这相当于 CPU 的 -crf 18（画质极好但文件极大），被误以为"GPU 编码出来的文件比 CPU 还大"——其实只是 CQ 值选错了。

7.3 Global Quality（Intel QSV）

ffmpeg -i 输入.mp4 -c:v hevc_qsv -global_quality 24 -c:a copy 输出.mp4

• Intel QSV 的恒定质量参数，取值逻辑与 CPU CRF 更接近（24 对 24）

7.4 QP 模式（AMD AMF）

ffmpeg -i 输入.mp4 -c:v hevc_amf -qp_i 28 -qp_p 28 -c:a copy 输出.mp4

• -qp_i：I 帧（关键帧）的量化参数
• -qp_p：P 帧的量化参数，通常与 -qp_i 设相同值

7.5 VBR 码率模式（有明确码率上限时）

ffmpeg -i 输入.mp4 -c:v hevc_nvenc \
  -rc:v vbr -b:v 2M -maxrate 3M -bufsize 5M \
  -c:a copy 输出.mp4

• -b:v 2M：视频目标码率 2 Mbps
• -maxrate 3M：最大码率上限，峰值不超过 3 Mbps
• -bufsize 5M：缓冲区大小，控制码率波动幅度（建议设为 maxrate 的 1.5-2 倍）
• 注意：M 必须大写，小写 m 在某些情况下不生效

八、NVENC 高级参数详解

以下参数针对 NVIDIA 显卡编码（hevc_nvenc / av1_nvenc）。

8.1 编码预设与调优

-preset p7 -tune:v hq

• -preset：编码速度预设，p1（最快）到 p7（最慢/最优质）。越慢压缩效率越高，同等画质文件更小。日常推荐 p4（平衡）到 p7（质量优先）
• -tune:v hq：调优目标为高质量（High Quality）；ull 是超低延迟（直播场景）；lossless 是无损

8.2 多遍编码

-multipass 2

• -multipass 2：两遍编码，第一遍分析，第二遍编码，压缩效率更高。编码时间增加约 30-50%，但文件更小或画质更好

8.3 前瞻帧数

-rc-lookahead 32

• -rc-lookahead：向前预看多少帧来辅助码率分配决策。范围 0-32，值越大压缩越好，速度越慢，推荐设 32

8.4 自适应量化（AQ）

-spatial-aq 1 -temporal-aq 1 -aq-strength 10

• -spatial-aq 1：空间自适应量化，开启（1）后，根据画面区域复杂度分配码率——纹理丰富的地方多给，大面积纯色的地方少给
• -temporal-aq 1：时间自适应量化，根据帧间运动量分配码率——运动剧烈的帧多给
• -aq-strength：AQ 强度，范围 1-15，推荐 8-12；值过高会导致码率分配失衡

8.5 GOP 结构

-g 300 -bf 4 -b_ref_mode 2

• -g 300：GOP 长度（关键帧间隔），每隔 300 帧放一个关键帧。GOP 越短，跳转越精确但压缩效率略降；推荐设为帧率 × 10（30fps 就设 300，60fps 就设 600）
• -bf 4：B 帧数量，范围 0-4。B 帧通过参考前后帧提升压缩效率，设 4 是上限
• -b_ref_mode 2：B 帧参考模式，2 是金字塔模式，压缩效率最高，推荐

8.6 分块多单元编码

-split_encode_mode 2

• -split_encode_mode 2：尝试调用多个 NVENC 编码单元（如 4090 有两个单元）。但实际调用几个取决于 FFmpeg 调度，不保证双倍速度

8.7 HEVC 10bit Profile

-c:v hevc_nvenc -profile:v main10 -pix_fmt yuv420p10le

• -profile:v main10：使用 HEVC Main10 Profile，支持 10bit 输出，必须配合 -pix_fmt yuv420p10le 使用

九、硬件加速平台

NVIDIA NVENC

# HEVC 10bit，质量优先
ffmpeg -i 输入.mp4 -c:v hevc_nvenc -pix_fmt yuv420p10le -profile:v main10 \
  -preset p7 -tune:v hq -rc:v vbr -cq:v 28 -b:v 0 \
  -multipass 2 -rc-lookahead 32 \
  -spatial-aq 1 -temporal-aq 1 -aq-strength 10 \
  -g 300 -bf 4 -b_ref_mode 2 \
  -c:a copy 输出.mp4

# AV1（需要 40 系及以上显卡）
ffmpeg -i 输入.mp4 -c:v av1_nvenc -pix_fmt yuv420p10le \
  -preset p7 -tune:v hq -rc:v vbr -cq:v 34 -b:v 0 \
  -multipass 2 -rc-lookahead 32 \
  -spatial-aq 1 -temporal-aq 1 -aq-strength 10 \
  -g 300 -bf 4 -b_ref_mode 2 \
  -c:a copy 输出.mp4

代际说明：16/20/30 系是第七代 NVENC；40 系是第八代，新增 AV1 硬编；50 系是第九代，速度略有提升。AV1 硬编是 40 系的重要分水岭。

Intel Quick Sync (QSV)

ffmpeg -i 输入.mp4 -c:v hevc_qsv -preset medium -global_quality 24 -c:a copy 输出.mp4
ffmpeg -i 输入.mp4 -c:v av1_qsv  -preset medium -global_quality 28 -c:a copy 输出.mp4

AV1 硬编需要 Intel Arc 独显或 Ultra 100 系列（14 代之后）核显。

AMD AMF

ffmpeg -i 输入.mp4 -c:v hevc_amf -preset balanced -qp_i 28 -qp_p 28 -c:a copy 输出.mp4
ffmpeg -i 输入.mp4 -c:v av1_amf  -preset balanced -qp_i 32 -qp_p 32 -c:a copy 输出.mp4

AV1 硬编需要 RX 7000 系列独显或 Ryzen 7000 系列的 700M 核显（如 7840H 的 780M）。

Apple VideoToolbox（macOS）

ffmpeg -i 输入.mp4 -c:v h264_videotoolbox 输出.mp4
ffmpeg -i 输入.mp4 -c:v hevc_videotoolbox -profile:v main10 输出.mp4

M 系列芯片支持 H.264 和 HEVC 硬编。AV1 编码支持情况视 FFmpeg 版本而定，请查阅对应版本文档。

十、hev1 与 hvc1：播放兼容性的那个坑

HEVC 视频在 MP4/MOV 容器中有两种打包标签，影响播放兼容性：

• hvc1：参数集（SPS/PPS）内联在容器 Sample Entry 中，视频开头一次性写入
• hev1：参数集可散布在码流中，每隔一段重复

FFmpeg 默认生成 hev1。 如需改为兼容性更好的 hvc1：

ffmpeg -i 输入.mp4 -c:v hevc_nvenc -tag:v hvc1 -c:a copy 输出.mp4

• -tag:v hvc1：强制将视频流的 codec tag 设为 hvc1

各平台兼容情况：

来自实际踩坑的建议：视频要在 iOS/Safari 播放，或者上传到 Web 播放器，加 -tag:v hvc1。用 hevc_nvenc 等硬件编码器有时会自动用 hvc1，用 libx265 软编默认是 hev1，最稳是显式指定。

十一、URL 作为输入，以及为什么不建议 URL 输出

11.1 URL 输入

ffmpeg -i "https://example.com/video.mp4?sign=abc123&token=xyz" 输出.mp4

为什么 URL 必须加引号？ URL 中常含 ?、&、= 等字符，在 shell 里有特殊含义（& 表示后台运行命令）。不加引号，shell 会在 FFmpeg 看到这个 URL 之前就把它"拆解"，导致参数传错或命令直接出错。

规则：URL 永远加双引号。

使用环境变量存储 URL（避免反复复制粘贴超长签名链接）：

export VIDEO="https://your-server.com/path/to/video.mp4?sign=very_long_token_here"
ffmpeg -i "$VIDEO" -to 120 -c:v hevc_nvenc -c:a copy 输出.mp4

注意 "$VIDEO" 也要有引号，防止变量本身展开后的内容被 shell 解析。

11.2 为什么不建议 URL 输出

FFmpeg 写入 MP4 文件时，必须在编码完成后回到文件开头写入 moov box（元数据，包含帧索引等信息），这个操作需要输出目标支持随机写入（seek）。

WebDAV 等网络存储协议通常不支持 seek 写入，会导致写入失败，或者输出的文件能写进去但无法正常播放。

结论：

• 输入：URL 可以用，注意加引号
• 输出：强烈建议输出到本地文件，完成后再上传。如果一定要直出，可以改用 MKV 格式（MKV 对 seek 要求更低），但兼容性不如 MP4

十二、视频变速

12.1 视频加速 / 减速

ffmpeg -i 输入.mp4 -vf "setpts=0.5*PTS" -c:a copy 输出.mp4

• setpts：修改视频帧的显示时间戳（Presentation TimeStamp）
• setpts=0.5*PTS：时间戳乘以 0.5 → 视频 2 倍速
• setpts=2.0*PTS：时间戳乘以 2 → 视频 0.5 倍速（慢动作）
• 规律：setpts = (1 ÷ 目标倍速) × PTS

12.2 音频加速 / 减速

ffmpeg -i 输入.mp4 -c:v copy -af "atempo=2.0" 输出.mp4

• atempo=2.0：音频 2 倍速
• atempo=0.5：音频 0.5 倍速
• ⚠️ atempo 取值范围是 0.5-2.0，超出范围需要串联多个：

# 4 倍速音频（超出范围，串联两个 atempo）
-af "atempo=2.0,atempo=2.0"

12.3 音视频同步变速

ffmpeg -i 输入.mp4 \
  -vf "setpts=0.5*PTS" \
  -af "atempo=2.0" \
  -c:v libx265 -crf 24 \
  输出.mp4

同时调整音视频速度，保持同步。注意变速后视频流发生了改变，不能用 -c:v copy。

十三、视频拼接与合并

13.1 文件列表拼接法（推荐）

新建文本文件 list.txt：

file '片段1.mp4'
file '片段2.mp4'
file '片段3.mp4'

ffmpeg -f concat -safe 0 -i list.txt -c copy 输出.mp4

• -f concat：使用 concat 解复用器，按列表顺序读取文件
• -safe 0：允许列表中使用相对路径（默认出于安全只允许绝对路径）
• -c copy：直接复制流，不重编码，速度极快

前提：所有片段的编码格式、分辨率、帧率必须完全一致，否则拼接结果会花屏或音视频不同步。格式不一致时，去掉 -c copy 改为指定编码器重新编码，代价是时间更长。

13.2 filter_complex concat 滤镜（格式不一致或需要重编码时）

ffmpeg -i 片段1.mp4 -i 片段2.mp4 -i 片段3.mp4 \
  -filter_complex "[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[outv][outa]" \
  -map "[outv]" -map "[outa]" \
  -c:v hevc_nvenc -cq:v 28 -rc:v vbr -b:v 0 -c:a aac \
  输出.mp4

• -filter_complex：复杂滤镜图，支持多输入处理
• [0:v][0:a]：第 1 个输入文件的视频流和音频流（方括号是标签，用于在滤镜图中引用）
• [1:v][1:a]：第 2 个输入文件……以此类推
• concat=n=3:v=1:a=1：拼接 n=3 段，输出 v=1 条视频流和 a=1 条音频流
• [outv][outa]：给滤镜输出命名，供后续 -map 引用
• -map "[outv]" 和 -map "[outa]"：选这两条流作为最终输出

13.3 时长不同时的对齐处理

场景：音频比视频短，补静音至视频时长

ffmpeg -i 视频.mp4 -i 音频.mp3 \
  -filter_complex "[1:a]apad[a]" \
  -map 0:v -map "[a]" \
  -shortest \
  输出.mp4

• apad：对音频末尾填充静音
• -shortest：以最短流为准截断输出，防止无限延伸

场景：填充到指定时长

-filter_complex "[1:a]apad=whole_dur=300[a]"

• whole_dur=300：音频填充/截断到恰好 300 秒

场景：视频比音频短，补黑帧

ffmpeg -i 视频.mp4 \
  -vf "tpad=stop=-1:stop_mode=black" \
  -af "apad" \
  -c:v libx265 -crf 24 \
  输出.mp4

• tpad=stop=-1:stop_mode=black：在视频末尾补充黑帧（-1 表示无限补，配合 -shortest 或音频时长决定何时停止）
• stop_mode=clone：改为复制最后一帧（冻结画面）

十四、VMAF 质量评估

VMAF（Video Multimethod Assessment Fusion）是 Netflix 开发的视频质量客观评估标准，模拟人眼感知，分数 0-100，95 分以上通常认为肉眼几乎无法区分与原片的差别。已内置在 FFmpeg 中，无需额外安装。

14.1 基本用法

ffmpeg -i 压缩后.mp4 -i 原始视频.mp4 \
  -filter_complex "[0:v][1:v]libvmaf=model=version=vmaf_v0.6.1:log_path='vmaf_log.txt':n_threads=20" \
  -f null -

• [0:v]：被测视频（压缩后）
• [1:v]：参考视频（原始），顺序不能搞反
• model=version=vmaf_v0.6.1：使用内置的 1080p 模型
• log_path='vmaf_log.txt'：结果写入日志文件
• n_threads=20：用 20 线程并行计算（设成你的 CPU 核心数即可）
• -f null -：不生成任何输出文件，只运行滤镜计算

14.2 4K 内容使用 4K 模型

-filter_complex "[0:v][1:v]libvmaf=model=version=vmaf_4k_v0.6.1:log_path='vmaf_log.txt':n_threads=20"

14.3 帧对齐问题

如果测出异常低的分数（比如平时都是 95 分，突然跳到 70 分），多半是帧没有对齐。在两个 -i 前各加 -r 帧率 强制同步：

ffmpeg -r 30 -i 压缩后.mp4 -r 30 -i 原始视频.mp4 \
  -filter_complex "[0:v][1:v]libvmaf=model=version=vmaf_v0.6.1:log_path='vmaf_log.txt':n_threads=20" \
  -f null -

另外，两个视频必须帧数和时长相同，建议测试前用 -to 裁剪到相同长度。

十五、完整命令参考

15.1 1080p HEVC 二压（NVENC，质量优先，兼容性标签）

ffmpeg -i 输入.mp4 \
  -vf "scale=-2:1080" \
  -c:v hevc_nvenc -pix_fmt yuv420p10le -profile:v main10 \
  -preset p7 -tune:v hq \
  -rc:v vbr -cq:v 28 -b:v 0 \
  -multipass 2 -rc-lookahead 32 \
  -spatial-aq 1 -temporal-aq 1 -aq-strength 10 \
  -g 300 -bf 4 -b_ref_mode 2 \
  -split_encode_mode 2 \
  -tag:v hvc1 \
  -c:a copy \
  -y 输出.mp4

15.2 1080p AV1 二压（NVENC 40 系，质量优先）

ffmpeg -i 输入.mp4 \
  -vf "scale=-2:1080" \
  -c:v av1_nvenc -pix_fmt yuv420p10le \
  -preset p7 -tune:v hq \
  -rc:v vbr -cq:v 34 -b:v 0 \
  -multipass 2 -rc-lookahead 32 \
  -spatial-aq 1 -temporal-aq 1 -aq-strength 10 \
  -g 300 -bf 4 -b_ref_mode 2 \
  -split_encode_mode 2 \
  -c:a copy \
  -y 输出.mp4

15.3 HEVC 码率上限模式（适合有明确码率要求的场景）

ffmpeg -i 输入.mp4 \
  -c:v hevc_nvenc -pix_fmt yuv420p10le \
  -preset p7 -tune:v hq \
  -rc:v vbr -b:v 2M -maxrate 3M -bufsize 5M \
  -multipass 2 -rc-lookahead 32 \
  -spatial-aq 1 -temporal-aq 1 -aq-strength 10 \
  -c:a copy \
  -y 输出.mp4

15.4 URL 输入，剪前 2 分钟，降至 720p

export VIDEO="https://your-server.com/path/video.mp4?sign=token_here"

ffmpeg -i "$VIDEO" \
  -to 120 \
  -vf "scale=-2:720" \
  -c:v hevc_nvenc -pix_fmt yuv420p10le \
  -preset p4 -tune:v hq \
  -rc:v vbr -cq:v 28 -b:v 0 \
  -c:a copy \
  -y 输出_720p.mp4

15.5 精确剪切并二压（起点帧精确，-ss 在 -i 后）

ffmpeg -i 输入.mp4 \
  -ss 00:01:30 -to 00:05:00 \
  -c:v hevc_nvenc -pix_fmt yuv420p10le \
  -preset p7 -tune:v hq \
  -rc:v vbr -cq:v 28 -b:v 0 \
  -c:a copy \
  -y 片段.mp4

15.6 关键帧快速剪切（秒出，不重编码）

ffmpeg -ss 00:01:30 -i 输入.mp4 -to 00:03:30 -c copy -y 片段.mp4

15.7 双 GPU 同时跑两个任务

# 终端 1（使用 GPU 0）
CUDA_VISIBLE_DEVICES=0 ffmpeg -i 视频A.mp4 \
  -c:v av1_nvenc -rc:v vbr -cq:v 34 -b:v 0 -preset p7 \
  -c:a copy -y 输出A.mp4

# 终端 2（使用 GPU 1）
CUDA_VISIBLE_DEVICES=1 ffmpeg -i 视频B.mp4 \
  -c:v av1_nvenc -rc:v vbr -cq:v 34 -b:v 0 -preset p7 \
  -c:a copy -y 输出B.mp4

15.8 VMAF 对比参考（草稿示例中的参数）

ffmpeg -i 参考视频.mp4 -i 被测视频.mp4 \
  -filter_complex "[0:v][1:v]libvmaf=model=version=vmaf_v0.6.1:log_path='vmaf_log.txt':n_threads=20" \
  -f null -

十六、常见问题与坑点

❌ 报错：Impossible to convert between the formats

完整错误：Impossible to convert between the formats supported by the filter 'Parsed_null_0' and the filter 'auto_scale_0'

原因：-pix_fmt p010le 与 scale 等滤镜不兼容

解决：把 -pix_fmt p010le 改为 -pix_fmt yuv420p10le

❌ 输出到 WebDAV 失败 / 输出文件损坏无法播放

原因：MP4 写入完成后需要 seek 回文件头写 moov box，WebDAV 不支持 seek 写入

解决：

1. 输出到本地，完成后手动上传（最稳）
2. 改用 MKV 格式输出（对 seek 要求更低）
3. 使用 rclone mount 并确认挂载方式支持 seek

❌ HEVC 在 Safari / iOS 不播放

把 -tag:v hev1 改为 -tag:v hvc1（或显式加上 -tag:v hvc1）

❌ 拼接后音视频不同步

• 检查各片段帧率是否一致，不一致先用 -r 统一
• -c copy 拼接要求时间戳连续，如果各片段来源复杂，改为重新编码
• 最稳方案：拼接时不用 -c copy，同时编码，代价是时间更长

❌ CQ 模式下文件比预期大很多

• 检查 CQ 值是否选错（参考上方 CRF/CQ 对应表）
• 加 -maxrate 和 -bufsize 限制峰值码率
• 检查 -b:v 0 是否有加（不加的话 NVENC 可能以默认码率为目标）

十七、参数速查表

持续更新。后续可补充：字幕烧录、色彩空间转换（HDR→SDR）、批处理脚本、更多滤镜参数等。

Composed by：Ryan Joseph Karazija/Andrew Scheps/Mike Lindsay

Wake
Heavy pulse
Bloody eyes
Sweaty clothes

New routine
That I've learned
To understand and know

Play my tricks
Fragile mind
Rest your head
On me

Shut my eyes
I'm not here
There must be some mistake

Don't be so serious
(×4)

Watch your words
Turn to dust
As we forget
As we move on

Still
I refuse
To let you slip away

Don't be so serious
(×4)

Magnets
(×n)

呜… 大过年的终于是把整个假期消磨在晚六朝三（六点睡十五点起；12 小时制）的离谱作息里了，过年前说好的写博客记录配置的豪言壮语也是不知道抛到哪里去了；趁着假期还没完全结束（我还没忘干净），就把我的一点心得记录一下吧。

背景

事情的起因是这样的：音色克隆是个危险的事情，把私有的数据交给云端，哪怕只有一句话，都有可能被日渐先进的技术去噪，扩增到几个小时，训练变声模型，巴拉巴拉拿来干什么就不知道了（没错我就是这么干的）。正好手上有 gpu 运算资源，VoxCPM 这种 Zero-Shot 的 TTS 效果也已经不错了，于是便打算本地部署一个推理服务。

推理

推理好啊，写成 OpenAI 兼容的 API 端点就可以无缝兼容各种成熟的应用了。正好，VoxCPM 的 README 里就有社区项目：voxcpm-fastapi，将原生调用包装成了 OpenAI 兼容的端点。

一顿操作猛如虎，一看推理速度5。在我的 RTX 4060 上，它的推理速度大概只有 5~6 it/s。尽管 RTF 勉强小于 1 吧，但现在的应用很少有实现流式 TTS 的 —— 其实技术复杂度挺高的，你需要类似 WebRTC 的实现，得到的就只是不需要像视频那样鼠标跟手的音频（又不是变声器）。而非流式就意味着热启动在几秒内不能生成一段不短的音频的话，直观感受就是挺慢的。

我也换到 RTX 4070 Ti Super 上试了下（是的，我的家里云有两张不同型号的N卡），上下文短的时候有 30 it/s 左右（其实这两张卡算力差距大概只是翻倍，这个推理速度差距大概率意味着 CUDA OOM 被 Windows 交换到内存了，这是推理服务这种计算密集型任务要极力避免的），但整个 pipeline 走完还是挺慢的。

关键是，原生 Pytorch 推理，不支持并发！FastAPI 的并发请求，就只能积压等待串行处理。作为一个用户会靠切分长请求解决高延迟和长上下文问题的服务，这显然是不可接受的。

咋办？回去翻 VoxCPM 的 README。还有一个社区项目，nanovllm-voxcpm，将 VoxCPM 里的 LLM 部分用 nanovLLM（一个使用 vLLM 优化思路达到相近的性能但轻量得多的 LLM 推理框架）实现了。

众所周知，vLLM 作为生产级的推理框架，显存优化和并发推理不是手拿把掐——于是让 LLM 帮我用它替换原生 Pytorch 推理，达到了 4060 上 ~30 step/s，4070 Ti Super 上 ~60 step/s，RTF 逼近不足 0.1 的性能。这对于我的应用场景已经绰绰有余（其实应该已经远超 VoxCPM 团队的预期了，但我没做详细测试，团队是在 4090 上测试的，也没啥比较的意义）。接下来，就是部署了。

部署

家里云嘛，能装 Windows 还装 Linux 多浪费；wsl 嘛，交互式用用还行，拿来跑服务就不太优雅了；至于 Docker，这么重的环境，也不够优雅；何况虚拟化必然有性能开销，尤其是对于计算密集型任务。然而众所周知，机器学习的推理对 Windows 平台并不友好。

首先，在原生 Pytorch 推理的时候torch.compile 需要的 triton 库就没有。这倒是好办，装对应版本（务必看清楚版本对应矩阵）的windows-triton就好了。（附：不 compile 的话大概是 4060 ~3 it/s, 4070 Ti Super ~17 it/s；compile的话加载模型会慢不少，是正常的）

然而，当换到 nanovLLM，依赖地狱才刚刚开始。vLLM 类框架需要的不只是 triton，还有 Flash Attention （flash-attn，一个更快的，显存更高效的注意力实现）。而这个东西，在 Windows 平台，没！有！预！构！建！编译这玩意儿大概在十几核的现代小型工作站（或者说，GitHub 的 CI Runner）上都要至少3个小时。幸好，GitHub 上有人 fork 了上传了预构建。只要下载安装对应版本（务必看清楚torch（包括cuda版本）和cpython的版本对应关系，以及预装相应版本的 CUDA Toolkit 并确保CUDA_PATH环境变量配置正确）即可正常运行。。。吗？

并不能。你大概率会收到报错：nccl 在 Windows 上不被支持。这是什么？这是分布式计算的后端。是，我知道我们没有用张量并行，理论上用不着分布式，但生产级的推理大概率不会是单卡的，为单卡额外维护一套逻辑没必要，典型的处理方法是起一个只有一张卡的“伪”分布式环境。然而，nanovLLM的分布式计算后端是硬编码的nccl 。那么，只要改成 Windows 可用的gloo ，就可以了。。。吗？

还是不能。因为：Pytorch 2.8~2.9 的内置gloo，是坏的！理论上这个问题在 2.10 应该已经修复（没试过，但 nightly 肯定是好的），但预构建的flash-attn 未必跟得上。所以，我直接回退到了 2.7 版本，重装了相关依赖（顺便提一句，如果是choco装的ffmpeg ,torchcodec会找不到它，但我已经提PR了），然后——

终于能正常运行了！看着龟速爬行的 tqdm 进度条被不断闪过的 200 响应日志取代，我只想说一句话：

我作业忘写了啊啊啊！！！

（PS：如果评论区有人感兴趣的话，我就抽空把我的方案精简一下以更“可部署”的方式分享出来）

2025高考已经结束了，全国一卷的英语第35题也是引起了不小的争议。下面，我将以普通在读高中生的视角，为大家带来我的解读。本文意在分享心得，因此请勿将其作为严谨的学术交流内容看待。

利益相关声明，我在撰写本文时是一位参与了2025年在英语科目使用全国一卷的地方的高考的高二年级学生，在真实的高考环境中完成了下面的题目，但同时这场高考对我来说无关紧要，因此本文仅以学习交流的视角谈谈我的看法。话不多说，我们先看看原题：

D篇

Microplastics have become a common source of pollution across the Earth—they have settled in the deep sea and on the Himalayas, stuck inside volcanic rocks, filled the stomachs of seabirds and even fallen in fresh Antarctic snow. They are even appearing inside humans.
Now, new research suggests that a simple, cheap measure may significantly reduce the level of microplastics in water from your tap (水龙头): boiling and filtering (过滤) it. In a study published Wednesday in Environmental Science & Technology Letters, researchers from China found that boiling tap water for just five minutes—then filtering it after it cools—could remove at least 80 percent of its microplastics.
Crucially, this process relies on the water containing enough calcium carbonate (碳酸钙) to trap the plastics. In the study, boiling hard water containing 300 milligrams of calcium carbonate led to an almost 90 percent drop in plastics. But in samples with less than 60 milligrams of calcium carbonate, boiling reduced the level of plastics by just 25 percent. Additionally, the research didn’t include all types of plastics. The team focused only on three common types—polystyrene, polyethylene and polypropylene—and they didn’t study other chemicals previously found in water such as vinyl chloride.
Still, the findings show a potential path forward for reducing microplastic exposure—a task that’s becoming increasingly difficult. Even bottled water, scientists found earlier this year, contains 10 to 1,000 times more microplastics than originally thought.
Scientists are still trying to determine how harmful microplastics are—but what they do know has raised concerns. The new study suggests boiling tap water could be a tool to limit intake. “The way they demonstrated how microplastics were trapped through the boiling process was nice,” Caroline Gauchotte-Lindsay, an environmental engineer at the University of Glasgow in Scotland who was not involved in the research, tells New Scientist. “We should be looking into upgrading drinking water treatment plants so they remove microplastics.”

32. How does the author present the issue in the first paragraph?
    A. By quoting an expert.
    B. By defining a concept.
    C. By giving examples.
    D. By providing statistics.
33. What determines the effectiveness of trapping microplastics in water?
    A. The hardness of water.
    B. The length of cooling time.
    C. The frequency of filtering.
    D. The type of plastic in water.
34. What does the author try to illustrate by mentioning bottled water in paragraph 4?
    A. The importance of plastic recycling.
    B. The severity of the microplastic problem.
    C. The danger in overusing pure water.
    D. The difficulty in treating polluted water.
35. What is Gauchotte-Lindsay's suggestion about?
    A. Choice of new research methods.
    B. Possible direction for further study.
    C. Need to involve more researchers.
    D. Potential application of the findings.

初次做题

首先，我们看看我在考场上的做题思路。第35题的关键线索是下面这句话：

We should be looking into upgrading drinking water treatment plants so they remove microplastics.

作为全文的最后一句话，它的位置符合题意“suggestion”；根据题意，答案与“research methods”或“more researchers”明显无关，A、C选项排除；文义“upgrading drinking water treatment plants”（升级饮用水处理设施）义即将上文发现的去除微塑料的方法应用于饮用水处理设施，从而从源头解决饮用水中含微塑料的问题，而非进行进一步研究，因此我选 D。

换位思考

下面，我们从出题者的角度，尝试剖析题目考察点。

关键词1：upgrade (upgrading)

根据生活中常用的语境：

Usage: apt [options] command Most used commands: upgrade - upgrade the system by installing/upgrading packages full-upgrade - upgrade the system by removing/installing/upgrading packages

RAID degraded

不难明白，upgrade在此处应指一种较为深度的，向好方向的更新，即使用某种方法减少微塑料；

关键词2：plant (plants)

根据《辐射：避难所》里电力设施被称为Power Plant，不难理解 plant 可泛指集中的基础设施，通常用于处理与供应基础资源如水、电、煤）。之于文中，即指水处理厂。以普通的英语学习者，该义项通常被视为一词多义，且错误理解为植物会较大程度上影响对文义的理解。

不难推测，文义为希望在上述研究的基础上，在饮用水供应的源头缓解微塑料问题，因此题目中即将其替换为将研究结果应用到水处理厂。

主要争议

然而，题目放出后，许多人认为本题选 B。主要理由如下：

1. D 选项工程上不可行

许多人认为，将大量饮用水“煮沸”并冷却过滤消耗大量能源，在工程上不可行。对此，我表示怀疑。人们的第一印象告诉自己，烧水需要较长时间，消耗大量能源，并在冷却过程中向环境大量散热。这是不对的。工程上对于这种需要对工质短暂调整温度，但产物和原料温度相差不大的处理，我们可以使用逆流换热来几乎完全回收热量。沿海干旱地区的海水淡化设施的推广，今麦郎等品牌的凉白开也证明“煮沸”饮用水并冷却过滤并非完全不可行。

2. 原文用词不同

“We should be looking into modifying drinking water treatment plants so they remove microplastics.”

根据英语原文，G.-L. 的本意并不直击大刀阔斧地升级水处理厂，自然希望进行进一步研究而非直接应用。但既然题目进行了修改，我们自然应当依照改文作答。

3. G.-L. 自述

I certainly wouldn't recommend boiling water at Drinking Water plants so certainly not option D.

网传一份网友询问 G.-L. 本人的邮件回复，其中教授表示题中四个选项均“非其本意”，但是B选项应当是最接近正确的。然而，阅读题中需要分析的是“作者对受访者话语的转达方式”，受访者的本意究竟如何并不该是决定答案的关键因素。

4. 常识判断

在饮用水处理设施中将水煮沸，并不是一个工程上可行，只是在此项研究见刊之前尚不清楚其净水作用的工业方案。在部分考生眼中——哪怕不是经过了专业的学习而是凭借一定的生活直觉——饮用水设施应用煮沸法就不是一个亟待讨论的新课题，而是一个已经可以宣判死刑的荒谬方案（至少在绝大多数正常生态/工业环境的社会中）。知乎

这种观点认为，文末 G.-L. 的评论与前文的煮沸法无关，而只是一个完全不相干的隔壁领域。作为一场全国性的英语语言考试，考生不该因为这种常识性的分歧而被扣去分数。

但是，假如说考生不希望常识性的分歧而被扣去分数，就应该在做题时完全摒弃常识，而忠于原文，寻找题目可能的暗示。这点，正是上面用词不同体现的出题人的暗示。

整理思路

在看了那么多争议后，我决定重新整理思路。

1. 重新理解文义

文中的发现，与其说是煮沸法除微塑料，不如说是硬水煮沸后微塑料会减少。这也解决了一个“中国人的问题”：我们千年以来都使用的“喝开水”，怎么就变成前沿学术成果了？文义并不单讲煮沸，而是在煮沸后进行了水的理化性质分析。

2. 重新理解选项

选项 D 说 potential 应用，而任何一项研究的应用都不是直接套用实验室做法。首先，水处理厂不可能为了去除微塑料而自降水质，直接把处理好的水变成硬水再煮沸过滤。从这个角度上来说，选项 D 是包含了选项 B 的 further research 的。既然我们认为 D 去除微塑料 was nice，而 D 又包含了 B，选更全面概括了 G.-L. 的评论的选项应当更合理。

因此，本题我选 D. Potential application of the findings.

NOT by AI

网页可能有渲染错误，建议移步 PDF 版

欢迎来到 ESP32C3TFT 开发板图片上传与固件管理指南！本指南将引导您完成安装图片与解决常见问题的全部流程。

1. 安装 Thonny IDE

Thonny 是一个简单易用的 Python 集成开发环境（IDE），它提供了良好的 MicroPython 支持。在本教程中，我们将使用 Thonny 来连接和管理 ESP32C3TFT 开发板。

1. 请访问 Thonny 官方网站：thonny.org 镜像地址
2. 下载适合您操作系统的版本（Windows、macOS 或 Linux）。
3. 按照提示安装 Thonny（通常只需点击“下一步”即可完成安装）。

2. 转换图片为 240x240 格式

由于本设备的显示屏分辨率为 240x240，为了确保较好的显示效果并节省存储空间，我们需要将图片转换为 240x240 的格式。

1. 准备您想要显示的图片。
2. 使用图像编辑软件（例如 Windows 系统自带的“照片”应用）打开该图片。
3. 将图片的大小调整为 240x240 像素。
4. 将调整好的图片保存为 PNG 格式。
5. 将图片文件重命名为您喜欢的名称。

3. 复制图片到开发板

1. 在 Thonny 中点击工具栏的“视图”选项，打开“文件”和“终端”面板。
2. 确保您的开发板已经连接至电脑。此时，在文件视图中您应该能够同时看到电脑和设备上的文件；在终端中也没有出现错误信息。
3. 在终端中键入 Control + C，直到显示以下内容： python MicroPython (固件版本) on (固件编译日期); ESP32C3 module with ESP32C3 Type "help()" for more information. >>> 如果连接出现异常，请点击页面上方的“Stop/Restart”按钮，然后重新连接设备。
4. 在电脑的文件系统中，导航至您转换好的图片所在的文件夹。
5. 在设备文件系统中，双击打开 imgs 文件夹。
6. 在电脑文件系统中，选中转换好的图片，右键点击并选择“上传到 imgs”。

常见问题

无法连接开发板

如果您将 ESP32C3TFT 开发板连接到电脑后，Thonny 无法检测到设备，请按照以下步骤检查连接是否正常：

1. 打开设备管理器（Windows）、系统报告（macOS）或使用 lsusb 命令（Linux）。
2. 查看是否有新的串口设备出现。如果没有，请尝试更换 USB 端口或 USB 线缆（确保您的 USB 线缆至少是 USB 2.0 的数据线）。
3. 如果有串口设备出现，但 Thonny 仍然无法连接，请尝试重新烧写固件。

如何烧写固件

这一步通常在设备出厂前已经完成。如果您的设备无法正常连接或需要更新固件，请按照以下步骤操作：

1. 确保开发板已经正确连接，并尝试在按下 BOOT 按钮的同时为设备上电。
2. 打开 Thonny IDE。
3. 在“解释器”选项卡中，点击“配置解释器”。
4. 点击“安装或更新 MicroPython（esptool）”。
5. 点击界面右下角的按钮 ☰。
6. 选择相应的串口设备作为目标设备。
7. 点击“选择本地 Micropython 镜像”（Select local Micropython image...）。
8. 选择包含 ST7789 驱动的适合的 MicroPython 固件文件（可以从这个仓库下载最新版或使用镜像地址，密码为 ESP32C3TFT）。

如何更新程序

如果您需要更新设备上的程序，请按照以下步骤操作：

1. 在这里下载所需的 dist.zip 文件。
2. 解压 dist.zip 文件。
3. 在 Thonny 中点击工具栏的“视图”选项，打开“文件”和“终端”面板。
4. 确保您的开发板已经连接至电脑。此时，在文件视图中您应该能够同时看到电脑和设备上的文件；在终端中也没有出现错误信息。
5. 在终端中键入 Control + C，直到显示以下内容： python MicroPython (固件版本) on (固件编译日期); ESP32C3 module with ESP32C3 Type "help()" for more information. >>> 如果连接出现异常，请点击页面上方的“Stop/Restart”按钮，然后重新连接设备。
6. 在电脑文件中，导航到解压后的 dist.zip 文件夹
7. 在设备文件中，右键删除所有文件（imgs中的文件可保留）
8. 在电脑文件中，选中 dist.zip 文件夹中的所有文件，右键点击并选择 “上传到 /”

希望本指南对您有所帮助！祝您开发愉快！

一、命名の暴力美学

「ESP32C3TFT」——这名字就像把泡面调料包全倒进去一样简单粗暴。主控 ESP32C3 +插拔式 ST7789 屏 + ADXL345 加速度计，齐活！当同龄人沉迷亚克力挂件时，我选择在书包上挂电路板——毕竟用 MicroPython 写个会动的电子挂件，可比塑料小人硬核多了。

二、现成方案の暴击

斥资购入某「ESP32C3TFT128」开发板后遭遇灵魂暴击：

• 防水玄学：前后壳像三明治包装，侧面裸奔接雨水
• 续航刺客：亮屏3小时自动关机，充电时温度直逼暖手宝
• 焊死美学：128x128 TN 屏自带斜视黑屏特效，焊死设计=换屏请买新板
• 休眠欺诈：DeepSleep 功耗和醒着时一样，仿佛在说"我睡了，但没完全睡"
• 插头寿命论：每天拔插 MX1.2 5接口，设计寿命几百次还废手指

三、硬件改造の奥义

电源系统の革命

• LDO退散：原板用 LDO 分压，USB 5V→3.3V 时 1.7V压降×电流=活体暖宝宝。换上 TLV62568 DCDC 方案效率起飞（德仪虽贵但香，自用必须堆料！）
• 充电芯片起义：杂牌IC换成 TP4056，实测可用手摸（原厂充电IC烫到能烤肉末）
• 二极管の背叛：试图用二极管做电源或门，结果锂电池最低 3.7V 经 0.7V 压降只剩 3V，连屏幕都点不亮
• MOS管救世：改用 SI2301 管理，USB 供电时自动切换电源路径，电池电压原厂直供不缩水

外设の尊严

• 屏幕自由宣言：换装国产 240x240 IPS 插接屏（8.4元/片，弄坏就换）
• 传感器の逆袭：ADXL345 共享 SPI 总线，中断引脚直连 GPIO3 实现免占用 SPI 触发休眠
• 按键自由：剩余 GPIO 全接按键开关，Micropython 自定义控制逻辑

玄学调试实录

• DeepSleep之谜：补上 32.768kHz 晶振后深度睡眠功耗直降（原厂竟省了这玩意！RTC时钟缺失导致休眠了个寂寞）
• 天线の诅咒：第一次外包画板显示屏线序接反，第二版换便宜PCBA连USB都认不出。最终天线周边铺满地——信号？能连WiFi就行！
• 叠层の美学：选 QFN 封装 ESP32C3 + 叠层 Flash，1.6mm 板厚控制完爆 3mm 厚的模块方案

原理图点这里

四、代码の炼狱

驱动の黑暗森林

• ST7789历险：致敬开源驱动！预编译固件旧版 MicroPython 计时器 bug（硬件计时器0和2能用，1号神秘消失），自行构建MicroPython v1.25.0解决
• ADXL345の试炼：全网唯一SPI驱动没有中断？啃完62页 datasheet 手搓代码（注释比代码长3倍），寄存器配置精确到bit级

内存の背叛

• OOM惊魂夜：gc.free_mem() 显示内存充足，但 bytearray() 死活分配不出来——用 mpy-cross 预编译后原地复活（文档警告：未经编译的.py文件注释过长会撑爆内存！）
• SPI总线の修罗场：忘记置高显示屏 CS 引脚，导致 ADXL345 读数全乱码（原来显示屏驱动不会自动释放总线！）

续航の黑魔法

• 摆烂检测器：ADXL345 中断触发静止超时，自动 DeepSleep（静止 uint8 max=255秒休眠）
• NVS存档术：用 ESP32 的 NVS 保存开机图片索引，避免每次改图片都要连电脑重命名文件
• 终极省电：关屏时切断屏幕背光供电+deepsleep（关屏待机≈电子尸体）

五、外壳の战争

• 初版亚克力壳：公差堪比山寨散装乐高，硬塞半小时后得分0.8（厂家：±0.5mm误差正常啦）
• 代工の真香：把板+壳打包寄回厂家代工组装（社恐の胜利：加钱能解决的事绝不自己动手）
• 透明の美学：2.7mm 亚克力拼接，成品厚度＜1cm，挂链加持后荣升书包最硬核挂件

六、成果发布会

• 续航奇迹：标称10小时，实际亮屏20小时+
• 温度の尊严：连续工作＜40℃，被窝使用安全认证√
• 防水の玄学：至少没被小雨当场送走（设计理念：只要水没淹到芯片引脚就算胜利）
• 社死名场面：在学校被问"这玩意能玩原神吗？"

后记：硬核浪漫

当同学们炫耀新挂件时，我默默掏出烙铁：「要给你焊个会动的吗？」——所谓极客的浪漫，就是把开发板变成随身携带的赛博护身符。

（项目成本核算：五个打板费79.84+元器件300.37+贴片费919.19+外壳定制250=1,444.95元。性价比？硬核玩家的事，能叫贵吗？）

技术宅的快乐：用20小时续航打脸商家参数，用透明外壳嘲讽工业设计，用自研驱动证明——有些坑，跳进去是为了爬出来时更闪耀。