想验证 Voyager 能不能跑完整流程，最短的路子是：准备一个只含单个素材的项目目录，把输入路径和输出路径都固定下来，从启动命令或界面入口把工具指到这个目录，跑一次生成，确认中间产物落在哪，再执行一次导出，最后用导出文件本身去核对。导入到导出的链路通了，再去谈产出质量和批量处理，才不会一开始就卡在环境或参数上。

适用场景：第一次接触 Voyager，或升级、换机器后想确认工具链是否完整。操作动作：单素材、单次生成、单次导出，输入输出路径先写死。验证方式：看中间产物落点、看导出文件能否打开且内容与输入对应。风险边界：这条最小链路只证明通路打通，不证明产出质量、速度或批量稳定性；配置里的字段名、命令里的参数名，都要以本机实际文件和 `--help` 输出为准。

建一个只放一个素材的项目目录并确定输出路径

先把变量压到最少：一个素材、一个项目目录、一个输出目录。素材建议选时长短、画面和声音都正常的文件，这样导出后容易判断内容对不对得上。目录大致长这样，具体名字可以按工具习惯调整。

voyager-min/
├── input/
│   └── sample.mp4
├── project.yaml      # 项目配置，文件名以实际为准
├── output/           # 导出目标
└── work/             # 中间产物落点，工具不支持自定义可留空

配置骨架只写和链路有关的字段，先不碰高级选项：

project:
  name: voyager-min
  input_dir: ./input
  output_dir: ./output
  work_dir: ./work
media:
  source: ./input/sample.mp4
  target_lang: zh      # 键名和取值以实际支持为准

不要照抄上面的键名。确认字段名的办法有三种：翻工具自带的示例配置（常见在 samples、examples、config 之类目录），跑一次不带配置看它报哪个字段缺失，或者打开界面里已有的项目看它写的是什么键。哪个方式先成功，就以那个为准。

在启动命令或界面里指向这个项目目录

目录准备好之后，要让工具读到它，而不是去猜某个默认位置。先看帮助，再拼命令：

voyager `--help`
voyager run `--help`
voyager run `--project` ./voyager-min `--config` ./voyager-min/project.yaml

子命令到底叫 run、generate 还是 process，参数是 `--project` 还是 `--workdir`，都以 `--help` 的输出为准，本文不假设具体参数名。如果工具只有界面入口，就在“打开项目”“选择工作目录”这类操作里指向 voyager-min 整个目录，而不是只选 input 里的单个文件。

这一步的验证方式是看启动日志：日志里应当打印出实际读取的输入路径和输出路径，和你配置文件里写的一致，并且没有在读取阶段就报文件找不到或字段未知。只要路径对不上，先改路径，不要急着调其他参数。

跑第一次生成并确认中间产物落在哪

启动之后，链路的第一段是否通了，看中间产物。常见落点有三类：项目目录下的 work、cache、tmp 或隐藏目录（如 .voyager）；系统临时目录（Linux 的 /tmp，Windows 的 %TEMP%）；输出目录旁边带 intermediate 之类的文件夹。不同版本、不同模式会选其中之一，所以要用查找而不是猜。

find ./voyager-min -type f -newer ./voyager-min/project.yaml
ls -laR ./voyager-min

判定成功的标准是：日志里出现阶段完成之类的提示、work 目录或临时目录出现非空文件、进程正常退出而不是报错中断。如果中间产物落在临时目录，要顺手记下这个路径，后面导出对不上内容时还得回来查。

执行导出并核对文件能打开、内容与输入对应

导出命令同样以 `--help` 为准，骨架通常是：

voyager export `--project` ./voyager-min `--output` ./voyager-min/output

导出后不要只看日志说成功，要按清单核对文件本身：

• 文件能被系统播放器或阅读器正常打开，不是零字节或无法解析；
• 内容与输入素材对应，比如时长、画面内容、语言方向对得上，不是空帧或错素材；
• 文件名和扩展名符合项目约定，方便后续批量脚本处理；
• 文件落点就在 output 目录，和配置里的 output_dir 一致。

任意一条不满足，说明链路后半段有问题，优先回到中间产物那一层排查，而不是重新搭目录。

把这套最小配置复制成模板复用

链路确认通了以后，把 voyager-min 整理成模板，后面新项目直接复制，不用重建结构。复制前先清掉产物，只保留骨架。

cp -r voyager-min voyager-template
rm -rf voyager-template/work/* voyager-template/output/*
# 保留一个占位素材或清空 input，按习惯处理

每次用模板时，需要替换的字段先列清楚再改：项目名、输入素材路径、输入输出目录（如果换位置）、目标语言或目标格式之类的业务参数，以及任何写死的绝对路径。替换后照样走一遍单素材生成和导出，确认新项目也能跑通，再开始加第二个素材或放开批量。模板的价值在于减少搭建变量，不在于替你保证产出质量，质量还是要回到单次结果上看。