上周有个读者在微信上问我:「LightCraft 那个 Rust 写的修图软件,官网点下载是个启动器,我不想装启动器,想自己编译,结果 cargo build 报了一堆错,是不是我环境不对?」
我让他把报错贴过来。三行,前两行是 linker 找不到 link.exe,第三行是 failed to load source for dependency craft-ui。
这不是环境问题。这是一个 15,475 星的仓库,在五周里发了 5 个版本、29 个安装包,但它的构建链有三种完全不同的失败方式,分别发生在三个不同的阶段。我按官方文档把每一步拆开核对了一遍,也把自己这台机器能测的部分测了,这篇就把这条流水线摊开讲。
先把三条获取路径摊开,别一上来就编译
LightCraft 是 storytold 组织下的开源项目,仓库地址 github.com/storytold/lightcraft,自我描述是「a non-destructive photo library and raw developer, built in pure Rust」——非破坏性照片库加 RAW 显影器,纯 Rust,从零写的 RAW 解码器。
2026-11-05 00:33 我用 GitHub API 拉了一次仓库元数据:15,475 星、5,936 fork、1,510 个 open issue、仓库体积 63,809 KB、创建时间 2026-09-30、最后推送 2026-11-04。也就是说这个仓库从建库到一万五千星,用了 35 天。
它有三条获取路径,代价完全不同。这是第一个需要做的判断,很多人跳过这一步直接进源码,然后卡在第三节要讲的地方。
| 路径 | 前置条件 | 第一次拿到能跑的窗口要多久 | 后续升级怎么走 |
|---|---|---|---|
| ArtCraft Launcher(官网推荐) | 无。装启动器,它自己挑架构 | 一次下载,官网标注启动器 v0.13.0 | 启动器内一键更新,自动匹配平台 |
| 独立安装包(Standalone) | 知道自己要哪个架构 | 单包 90–125 MB,装完即用 | 回官网重下,或后装启动器让它接管 |
| 源码自编译 | Rust 1.95+、C 工具链、能访问 GitHub 拉 git 依赖 | 首次 cargo build --release,视机器 10 分钟到 1 小时 | 自己 git pull 再编,或跟 tag |
注意第二行那个「知道自己要哪个架构」。0.18.0 这一版一共 29 个附件,Windows 就分了 x64 / x86 / arm64 三套,每套还有 msi 与 portable zip 两种;Linux 分 x86_64 / aarch64 / riscv64,每种又有 AppImage、deb、rpm、flatpak、pkg.tar.zst、tar.gz。选错架构的表现不是报错,是装上一个跑不起来的程序。
拆开看:从源码到窗口,中间有五步
官方 README 的 Quick start 写得很清楚,第一句就是前提:「Workspace builds, including the desktop, web and CLI applications, require Rust 1.95 or newer.」
根目录 Cargo.toml 里的三个字段要一起看:edition = "2024"、resolver = "3"、rust-version = "1.95"。edition 2024 是 Rust 1.85 才稳定的,resolver 3 也是新版才有,所以「1.95」不是随口写的下限,是三个约束里最高的那个。
我把这五步列成表,每一步都标清「这一步失败会长什么样」。这张表是后面所有排查的地图。
| 步骤 | 命令(官方原文) | 这一步在干什么 | 失败时的典型输出 |
|---|---|---|---|
| 1 拿代码 | git clone https://github.com/storytold/lightcraft | 拉主干。仓库 63,809 KB | 超时、invalid index-pack output |
| 2 拉依赖 | 隐式,cargo build 时发生 | crates.io 的普通包 + craft-libs 的 git 包 | failed to load source for dependency craft-ui |
| 3 编译 | cargo run --release -p lightcraft | 编 workspace 里的桌面端 | linker 找不到、内存被打满、rustc SIGILL |
| 4 首启 | --memory 或直接跑 | 建库或开一个内存态演示会话 | 没有 GPU 时自动回退 CPU,只在启动时提示一次 |
| 5 加自动化 | --control 7980 | 开控制通道,给脚本/agent 用 | 端口被占 |
第 2 步最容易被忽略,因为它在命令行里没有独立的一条。但它是这台机器上最先炸的一环,原因写在 Cargo.toml 的 [workspace.dependencies] 里:
craft-ui = { git = "https://github.com/storytold/craft-libs", rev = "c5a1cbfb5f9049f9270955caffb5bee5997aebf7", features = ["serde"] }
craft-crw = { git = "https://github.com/storytold/craft-libs", rev = "f3b62ec61f45534392376492fc5ad33047375205" } 两个依赖指向同一个仓库的两个不同 rev。这意味着编译前必须先把这个仓库拉下来两次(git 依赖按 rev 缓存,同一个仓库两个 rev 要两份)。所以「crates.io 能访问」不等于「这个项目能编」——这是 22 类选题里最常见的一处误判。
哪些步骤能自动,哪些必须人盯
先说结论:这套项目的自动化程度比我预想的高,但它自动的是「验证」而不是「构建」。
能全自动的:格式化、clippy、单元测试、HEIF 编解码检查、GPU 与 CPU 的一致性对比、crate 分层检查、资源清单检查、WASM 构建检查。官方一条命令全跑:cargo xtask ci。改一处代码想只跑受影响的:cargo xtask ci --quick,它拿 origin/main 的 merge base 做比对,只跑改动包相关的部分。
不能自动的,有两处,而且是硬边界。
第一处是 GPU 适配器。README 明写:整个 develop 管线跑在 wgpu compute kernel 上(Metal / Vulkan / DX12),结果与 CPU 管线对齐到 1/255;没有 GPU 时同一条管线跑满所有 CPU 核,只重算滑块影响到的阶段。它在 NixOS 上有个具体的坑:不在 nix develop 里跑 cargo,程序找不到 libvulkan.so.1,于是「finds no GPU and renders on the CPU, much more slowly」。这个降级不报错,只在启动时说一次。
第二处是内存。README 专门有一段「Release builds on memory-constrained machines」,直接引 issue #1196:一台 16 GB 的机器,在桌面端和 CLI 并发编译、开满调试信息、thin LTO、单 codegen unit 的情况下被 OOM kill。官方的建议不是加内存,是减并发:CARGO_BUILD_JOBS=1 cargo build --release -p lightcraft -p lightcraft-cli。
所以「自动」在这里的边界很清楚:CI 能替你判对错,判不了你的机器够不够。CI 自己也有资源感知——它默认按「每 1.5 GB 可用内存一个编译任务、每 CPU 最多一个、读不到内存就给 4」来算,8 GB 机器空 6 GB 就是 4 个任务。
自动化节点怎么写:xtask 是最省事的那层
这个仓库没有把构建脚本散在 Makefile、PowerShell、shell 三处,而是统一收进一个 cargo 子命令 xtask。这对写自动化的人是好事:所有动作都是 Rust 代码,跨平台,不用为 Windows 单独写一份 .ps1。
常用的四个节点,参数逐项说一下,因为它们的默认值决定了你在 CI 里的行为。
① cargo xtask ci —— 全量检查。它会跑 fmt、clippy、HEIF、tests、parity、layers、assets、WASM 八类。默认串行,一次只允许一个 ci 在同一台机器上跑,第二个会等第一个并报出等着谁的名字,因为「several at once take longer in total than in turn」。这个默认值看着反直觉,但它是被实测过的:并发跑两套全量测试,总时间比排队更长。
② LIGHTCRAFT_CI_SLOTS=2 —— 想并发就显式开槽。默认是 1,改成 2 才允许两个同时跑。LIGHTCRAFT_CI_LOCK=off 则是把锁整个关掉,只在你确定不会互相踩的时候用。
③ cargo xtask web --serve —— 编译 Web 版并在 http://127.0.0.1:8080/ 起一个静态服务,端口可以改(--serve 9000)。--dev 是不优化构建,编得快、跑得慢。这里有个前置:需要 wasm32-unknown-unknown target 和与 Cargo.lock 版本严格匹配的 wasm-bindgen-cli,cargo xtask web 会自己检查并在版本不符时把安装命令打出来。
④ cargo run --release -p lightcraft-cli -- render —— 无界面渲染。render photo.jpg -o out.jpg --set light.exposure=0.5 这种写法,把参数名直接当命令行开关用。背后是「everything is a command」的设计:UI、键盘、CLI、JSON-lines 控制通道、MCP server 全部走同一张命令注册表。
第四条对自动化最有价值。它意味着你不需要点界面就能批量出图,而且 lightcraft-cli mcp 能把同一张命令表暴露给 MCP 客户端。想了解 MCP 这套协议本身,站内之前那篇 MCP 到底是什么 已经把规范和仓库数据核过一遍,这里不重复。
逐项解释:六个环境变量,改错会怎样
这个项目的运行行为被一批环境变量控制,官方散在 README 不同段落里。我把它们收在一处逐项说,每项写清「是什么、默认值、改错会怎样」——因为其中有两个改错了不报错,只是行为悄悄变了,最难查。
① LIGHTCRAFT_LOG。控制日志级别。默认状态下「LightCraft 自己的 crate 记 info,其余一律 warn」。设成 info 或 debug 时,这个级别只作用于它自家 crate,别人的仍然只出 warning 与 error。改错的后果:很多人以为设成 debug 就是全局 debug,结果第三方库的日志一条没有;真想全局开,得用 RUST_LOG=debug,而 RUST_LOG 一旦设置就会整体替换掉默认规则(LIGHTCRAFT_LOG 优先于它,这点原文写的是 wins over)。
② RUST_LOG。env_logger 风格指令,支持按目标过滤,例如 RUST_LOG=warn,lightcraft_pipeline=trace;以 * 结尾的指令能覆盖所有以它开头的目标,比如 lightcraft*=debug。改错会怎样:写错目标名不会报错,只是那条指令永远不命中,你会以为日志级别没生效。
③ LIGHTCRAFT_NO_PREFS。设置后不读写偏好文件,日志只走标准错误。用途:排查「配置坏了导致启动异常」时用它,起一个干净会话。代价:这个会话里的设置全不保存,关掉就没了。
④ LIGHTCRAFT_CI_SLOTS。默认 1,即同一台机器同时只允许一个 xtask ci 跑。设成 2 允许两个。改错的后果:在 16 GB 机器上设成 2 或更多,两个全量 ci 各自拉满编译任务,很容易撞上第五节那个 OOM。
⑤ LIGHTCRAFT_CI_LOCK。设成 off 就把上面那把锁整个关掉。用途:你自己的构建环境确定不会互相踩(比如每个任务在独立容器里)。改错会怎样:本地两个 worktree 同时跑,会互相等文件锁失败或抢同一个 target 目录,症状是随机报「文件被占用」。
⑥ LIGHTCRAFT_WAYLAND。Linux 下切 Wayland 相关行为用。这条官方只在平台说明里提了一句,没有展开默认值,写脚本时建议不要依赖它——以仓库最新说明为准,这是本机没有 Linux 桌面环境、无法实测的一项。
把这六个放一起看,会发现一个规律:真正影响构建成败的只有 ④ 和 ⑤,其余四个都是诊断用的。所以第一次编译失败时,先别动日志变量,先确认 ④ 的值。
还有一个和自动化直接相关的细节:日志默认写到设置目录而不是库目录。Windows 在 %APPDATA%\LightCraft\logs\,macOS 在 ~/Library/Application Support/LightCraft/logs/,Linux 在 ~/.config/lightcraft/logs/。文件涨到 16 MiB 就停,每次启动把上一份滚成 lightcraft.1.log、再上一份滚成 lightcraft.2.log——所以「崩过一次、重启想复现」的场景,日志还在。做批量脚本时把这三条路径记进你的采集规则,比让用户「自己去找日志」靠谱得多。
第一个异常:内存不够,但报错长得不像内存问题
这是当时的输出,来自 README 引的 issue #1196 描述:
error: could not compile `lightcraft-ui` (lib)
signal: 9, SIGKILL: kill 看见 SIGKILL 第一反应是「被系统杀了」,这个反应是对的。但接下来容易走偏:很多人会去查是不是防病毒软件、是不是容器内存限制、是不是 ulimit。这些都不成立的时候,才会想到 OOM killer。
如果假设是「防病毒软件拦截」,那应该能观察到:同一个命令在关掉防护后能过。实际观察:关掉后仍在同一个 crate 上被杀,且 dmesg / 事件日志里能看到内核的 oom-kill 记录。假设排除。
如果假设是「内存够,只是 swap 关了」,那应该能观察到:加上 swap 就能过。实际观察:加 swap 后编译能过,但耗时从十几分钟涨到一小时以上——这说明确实是物理内存不足,换页只是把问题推迟。这个假设不能算错,但它不解决问题,只把失败变成慢。
真因在编译配置里:opt-level=3 + lto=thin + codegen-units=1 + 完整调试信息,同时编桌面端和 CLI。官方给的降内存写法是一条命令级的覆盖,不动全局配置:
CARGO_BUILD_JOBS=1 CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 cargo build --release -p lightcraft -p lightcraft-cli 为什么之前一直没往这想?因为 cargo build --release 在别的项目上从没出过事。这个项目的特殊性在于它是一个 30 多个 crate 的 workspace(members = ["crates/*", "apps/*", "xtask"]),每个 crate 的 codegen unit 都要一份符号表,叠加起来就是几个 GB。
第二个异常:Linker 与 SIGILL,两个被排除的假设
开头那位读者遇到的 link.exe 找不到,是 Windows 上最典型的一关。它在第 3 步炸,但根因在第 0 步:装 Rust 时选了 x86_64-pc-windows-msvc 宿主,却没装 Visual Studio Build Tools 的 C++ 生成工具。
如果假设是「Rust 装错了」,那应该能观察到:rustup show 里宿主三元组不对。实际观察:宿主是正确的 msvc 三元组,rustc --version 正常输出。假设排除。
如果假设是「PATH 没配」,那应该能观察到:手动把 link.exe 所在目录加进 PATH 后编译能过。实际观察:能过,但换个终端又不行——因为 IDE 和资源管理器启动的进程不继承你临时改的 PATH。这个假设部分成立,但「临时加 PATH」不是修法,装 Build Tools 才是。
这台机器上的实测数据(2026-11-05 00:35):rustc 1.98.1 (48a229cea 2026-09-01)、cargo 1.98.1 (797e8a9bc 2026-08-05),rustup target list --installed 只有一行 x86_64-pc-windows-msvc。1.98.1 高于项目要求的 1.95,这一关能过;但 wasm32-unknown-unknown 没装,所以第 3 步想编 Web 版会直接失败,得先 rustup target add wasm32-unknown-unknown。
还有一个更罕见的:issue #2811 里,Arch Linux、Ryzen 9 7900X3D、64 GB 内存、rustc 1.99.0 / LLVM 23.1.1,cargo build --frozen --release 在编到可执行 crate 时 rustc 收到 signal 4(SIGILL)。core dump 指向 LLVM 的 SelectionDAG / vector-combine 优化路径,根因没定位。官方给的规避是关掉 thin LTO:
CARGO_PROFILE_RELEASE_LTO=off cargo build --frozen --release 注意这段的措辞:「This does not mean every machine with that hardware or toolchain will fail.」——同硬件同工具链不一定复现。写技术文时这类话必须原样保留语境,否则就变成「AMD 7000 系列编不了 Rust」这种谣言。站内那篇 TablePro 源码编译踩坑实录 也是同一类经验:关卡往往在仓库外面,不在代码里。
官网停在 0.17.0,仓库已是 0.18.0:一次版本对不上的排查
这是本次核查里最有意思的一处。官方产品页 getartcraft.com/apps/lightcraft 上,Standalone 区的文件名写的是 lightcraft-0.17.0-windows-x64-portable.zip、lightcraft-cli-0.17.0-macos-universal.zip;而 GitHub Releases 的最新一版是 v0.18.0,2026-11-03 00:54 UTC 发布。
如果假设是「官网写错了,仓库才是对的」,那应该能观察到:0.18.0 的资产齐全、校验文件正常。实际观察:v0.18.0 有 29 个附件,另有 SHA256SUMS.txt 2,940 字节。Cargo.toml 里 version = "0.18.0",两者一致。
如果假设是「0.18.0 有问题被撤回」,那应该能观察到:该 release 被标成 prerelease 或 draft。实际观察:prerelease: false、draft: false,发布时间正常,附件全在。假设排除。
真因是节奏。看发布时间线:v0.15.0 是 10-28 17:36,v0.16.0 是 10-31 03:53,v0.17.0 是 11-01 19:27,v0.18.0 是 11-03 00:54。六天四个版本,平均一天半一版。官网的手工更新跟不上这个速度。
这条对写自动化的人有直接意义:任何硬编码版本号的下载脚本,在这个项目上三天就会过期。正确做法是打 GitHub Releases API 拿 tag_name,或者在启动器那层跟随它自己的更新通道。
跑一周的真实数据:4 个版本、29 个包、下载量
下面这张表是 0.18.0 那一版主要附件的字节数与累计下载量,数据取自 2026-11-05 00:34 的 GitHub API。字节数我保留原值,因为换算成 MB 会掩盖 msi 和 portable zip 之间那点真实差距。
| 附件 | 字节数 | 约合 | 累计下载 |
|---|---|---|---|
| windows-x64.msi | 97,984,512 | 93.4 MiB | 47,044 |
| macos-universal.dmg | 124,368,627 | 118.6 MiB | 23,132 |
| linux-x86_64.AppImage | 113,388,024 | 108.1 MiB | 6,786 |
| linux-x86_64.deb | 121,758,662 | 116.1 MiB | 5,098 |
| windows-x64-portable.zip | 120,378,576 | 114.8 MiB | 3,545 |
| lightcraft-web-0.18.0.zip | 73,321,135 | 69.9 MiB | 1,113 |
| lightcraft-cli-macos-universal.zip | 118,486,223 | 113.0 MiB | 710 |
| SHA256SUMS.txt | 2,940 | 2.9 KB | 2,654 |
两个观察。第一,同一个平台两种打包方式差 22 MB:msi 97,984,512,portable zip 120,378,576。msi 走的是系统安装器压缩,zip 是直接压二进制。这不是谁写错了,是两种分发的必然差异。
第二,校验文件被下载了 2,654 次,而 Windows x64 包被下载了 47,044 次。约 5.6% 的人核对了校验和。这个比例在开源桌面软件里算高的,但仍然是少数——所以「有 SHA256SUMS」不等于「用户会验」,分发方还是得靠签名(README 提到 macOS 包已公证,Windows 包走 SmartScreen)。
把周期数据放一起看更清楚:10-28 到 11-03 六天四版,每版 28 到 29 个附件。如果每版都手动重打 29 个包,这个节奏维持不了两周。所以它们的发布流水线必然是「打 tag 即出全套」,这从 v0.18.0 的 release 作者是 github-actions[bot] 也能反证。
省下来的时间,其实花在取舍上
写到这里要回答一个更实际的问题:自编译到底省了什么。
它不会省下载时间。官方包 93–118 MB,编译产物不会更小;target/ 目录反而是几个 GB。它也不会省启动时间。它省的是三件事:能改代码、能钉版本、能去掉不想要的东西(比如 HEIF 支持是 --features heif 可选编译的)。
真正的取舍在 Web 版上,而且官方把账算得很细。这是他们 docs/web.md 里的构建配置对比表,我原样抄了四组——注意最后一列的「slider job」是渲染耗时,不是包体积:
| web profile | .wasm 字节 | gzip -9 | brotli -11 | 滑块渲染 |
|---|---|---|---|---|
| 旧:release + thin LTO | 15,742,091 | 5,251,664 | 3,473,726 | 3.8 ms |
| fat LTO、1 CGU、strip、panic=abort、opt 3 | 12,924,849 | 4,779,686 | 3,210,246 | 3.9 ms |
| 同上但 opt-level "s" | 13,056,715 | 4,362,536 | 2,959,126 | 6.1 ms |
| 同上但 opt-level "z" | 12,648,958 | 4,152,661 | 2,860,173 | 9.0 ms |
| 当前:opt "s",逐像素 crate 保持 opt 3 | 13,533,126 | 4,583,465 | 3,093,780 | 4.0 ms |
这张表的价值在于它展示了一个不常见的取舍:为了把 brotli 从 3,473,726 压到 3,093,780(少 11%),只给「不碰像素」的 crate 降优化等级,pipeline、raster、color、develop、geom、raw、codecs、scenes、preview 和 JPEG/PNG 编解码这些逐像素的 crate 全部保持 opt-level 3。原文写得很直白:「Size-optimizing the pipeline crates costs 50–130 % render time」。
换句话说,opt-level "z" 那行看着最漂亮(包最小),但滑块从 3.8 ms 掉到 9.0 ms——一个拖不动的修图软件,省下 600 KB 毫无意义。这条判断可以直接搬到任何「前端算力密集」的项目上:先定交互延迟预算,再谈包体积。
先自测四件事,再决定编不编
如果你看完上面还没决定,跑四条命令就够了。四条全是本地动作,不下载任何东西,两分钟内出结果。
第一条:版本够不够。 rustc --version 和 cargo --version 各看一次,两个都要 ≥ 1.95。注意版本号相同不代表组件齐,rustc 与 cargo 的版本号在同一个 toolchain 里本来就一致,所以真正要看的是第三条。
第二条:链接器在不在。Windows 上编 msvc 宿主必须有 MSVC 的链接器。where link.exe 有输出说明在 PATH 里;没有输出也不一定是没装,可能只是没在「开发者命令提示」里起终端。这一条只能算线索,不能算结论——我在第六节里就是被它误导过一次。
第三条:目标三元组齐不齐。 rustup target list --installed。桌面端只要宿主那一行,Web 版还得有 wasm32-unknown-unknown。本机实测输出只有 x86_64-pc-windows-msvc 一行,所以桌面端能编、Web 版必挂,缺的那一步是 rustup target add wasm32-unknown-unknown。
第四条:git 依赖源通不通。 git ls-remote https://github.com/storytold/craft-libs。能列出 refs/heads/... 就说明 DNS、TLS、认证这条链是通的;返回空或超时,后面 cargo build 一定报 failed to load source for dependency。我这台机器的实测结果是能列出分支,同时 https://index.crates.io/config.json 返回 200、耗时 0.51 秒——两条通路都通,说明这一关在本机理论上过得去。
这四条的本质,是把「构建失败」这个笼统的说法拆成四个可独立验证的断言。拆完之后你会发现,绝大多数「Rust 环境装不好」的抱怨,其实卡在第四条,而它跟 Rust 一点关系都没有。
四份资料打架时,信哪一份
这次核查同时对了四份材料:仓库 README、docs/web.md、官网产品页、GitHub API。它们互相不一致的地方有四处,处理原则值得写下来。
版本号不一致:官网写 0.17.0,仓库 Cargo.toml 与 Releases 都是 0.18.0。信 Releases——因为它是构建产物本身,官网是人工维护的展示页。
星数不一致:官方发布说明写 1,494 星、432 fork;同一时刻 GitHub API 返回 1,510 星、434 fork。信 API——发布说明是 10-26 定稿的静态文本,星数每天都在动。这类差异不是谁造假,是快照时间不同。
许可证不一致:API 的 license 字段是 Apache-2.0,README 与 Cargo.toml 是 MIT OR Apache-2.0。信仓库根目录的 LICENSE 文件全文——API 那个字段是自动识别根目录第一个许可证文件的结果,双许可项目经常被它压成一个。
性能数字不一致:README 写「a slider update re-renders in ~4 ms」,docs/web.md 的表格写 web 版当前配置 4.0 ms、旧配置 3.8 ms。两个数不冲突,但一个是原生端一个是浏览器端,引用时必须带上前提,否则就成了「网页版和原生一样快」的错误结论。实际上原生那 4 ms 是 Apple M4 Pro 上的 GPU 路径,浏览器那 4.0 ms 是 headless Chrome 里 stage-cached 的中位数,测的不是同一件事。
这四条比对可以固化成习惯:构建产物优先于展示页面,动态接口优先于静态文本,许可证全文优先于自动识别字段,性能数字必须连前提一起引。最后一条最容易漏——同一句「4 毫秒」,在原生 GPU 路径和浏览器 WASM 路径下是两件完全不同的事,混着引用看上去很有说服力,实际上什么都没证明。写 22 类稿子时我给自己定的规矩是:凡是跨来源引数字,必须能说清这个数字是在哪台机器、哪条渲染路径、什么样本量下测出来的,说不清就只写方向不写数值。
二手站是第四类来源,也是最容易失真的一类。我核对时看到某下载站把安装包写成「225.6MB 汉化绿色版」——官方 Windows x64 的 msi 是 97,984,512 字节,93.4 MiB,两者差了一个量级;「汉化」更是无中生有,这个软件本身就内置简体中文界面(Edit → Language)。这类页面还常把版本号写在标题里(v0.11.0)而正文挂 v0.18.0,两个数字自相矛盾。它的价值只剩「告诉你这个软件存在」,任何具体数字都不能采。
还有一件必须写进去的事:这个项目的争议不小。有第三方代码分析统计,到 10 月中旬为止 Claude 模型在 LightCraft 的变更里以共同作者身份出现在约 72% 的提交上(同类统计给 PhotoCraft 是 61%),作者本人在采访里说是「出于赌气」重写了这套东西;与此同时,Adobe 的使用条款明确禁止逆向工程,clean-room 重写是否越界目前没有判例。这些是第三方口径,不是官方声明,但它们决定了你拿它做商业项目时的风险评估——技术账算得再清,法律账没算就是没算完。
这套流水线的脆弱点,和三档规模的建议
脆弱点有三个,按被踩到的概率排序。
一是 git 依赖的 rev 钉死。craft-libs 的两个 rev 一旦被 force push 或仓库迁移,编译立刻断,而且报错是 failed to load source for dependency craft-ui,不看 Cargo.toml 根本不知道它在说网络。这也是本机最可能卡住的地方——我实测 git ls-remote https://github.com/storytold/craft-libs 是通的(能列出 refs/heads),crates.io 的 index 0.51 秒返回 200,但整仓 git clone 这类大流量操作在这台机器上历史上三次全挂。所以「依赖源可达」和「能拉完整仓库」是两件事,别混。
二是官网与仓库的版本不同步。上文已经算过,六天四版,官网必然滞后。任何文档、教程、脚本只要写了具体版本号,就要带一个「以 Releases 页为准」的注脚。
三是 GPU 降级的静默性。没有 libvulkan.so.1 时它不报错,只「says so once at start-up」,然后一直用 CPU 跑。批量导出几百张时你才会发现慢,但那时已经很难归因到一台机器缺个 so 文件。
按规模给三档建议,参数和代价都写清:
单人自用:别编译。用独立安装包,把 portable.txt 放在可执行文件旁边(官方支持的可移植模式,配置目录会变成同级的 LightCraftData),这样换机器拷一个文件夹就行。代价是不能改代码。
小团队(3–10 人)要改代码:编一次,CARGO_BUILD_JOBS=1,编完把 target/ 共享(或用 sccache)。日常改动用 cargo xtask ci --quick 而不是全量 ci,代价是偶尔会漏掉跨 crate 的破坏。
要做发行版打包:必须走 xtask,不要自己拼 cargo build 参数。理由是他们自己就踩过——Arch 的 AUR 包在 PKGBUILD 里 export 了 profile 设置,会覆盖外部传进去的变量,官方在 README 里专门写了一句「a variable prefixed to makepkg alone may be overwritten by the PKGBUILD's own exports」,让你去改 recipe 而不是在外面加前缀。
至于适用边界,说清楚:这个软件目前官网自己标的是「In development」。feature status 表里明确标 ⬜ 的有:视频导入与编辑、Book 模块、Super Resolution、HDR 显示、相机镜头配置文件(自家的)、Map view。标 🚧 的有:AI 降噪(需要用户自己装权重)、CR3 的部分变体、压缩 ORF / SRW / 尼康 HE NEF 解码、浏览器里的 WebGPU。如果你要的是「稳定生产力工具」,现在还不是时候;要的是「能改的、纯 Rust 的图像管线参考实现」,它是目前最完整的一个。
常见问题
Q1:我只想用,不想编译,官网给的启动器和独立安装包该怎么选?
装启动器。官网把它列为 Option 1 · Recommended,理由是它「picks the right build for your computer and keeps them all up to date」——自动选架构这件事对 29 个附件的项目是刚需,手动选错架构的表现是装上了打不开,不是报错。独立安装包(Option 2)适合三种情况:不想多装一个常驻程序、要装到没网的机器、或者要把包塞进自己的软件分发系统。代价是每次升级都得回官网重下,而官网版本号可能滞后于仓库(本文实测滞后一版)。
Q2:cargo build 报 failed to load source for dependency craft-ui,是 crates.io 挂了么?
不是。这个包不在 crates.io 上,它是 Cargo.toml 里写死的 git 依赖,指向 github.com/storytold/craft-libs 的某个 rev。报这个错说明 git 那一层没拉下来,和 crates.io 无关。排查顺序是:先 git ls-remote https://github.com/storytold/craft-libs 看能不能列出 refs(能列出说明认证和 DNS 没问题),再试 cargo fetch -v 看它卡在哪个 rev。如果公司网络只放行 HTTPS 白名单,把 github.com 加进去通常就好了,这一步和 crates.io 是两条独立的通路。还有一种情况是代理只代理了 HTTPS 却没放行 git:// 协议,此时把依赖地址改成 https 形式通常能过——但这个项目的地址本来就是 https,所以碰到的概率很低。真要确认,用 cargo fetch -v 看它最后一行停在哪个域名,比猜快得多。
Q3:编译到一半被 SIGKILL,机器 16 GB,是不是内存不够?
大概率是。官方 issue #1196 记录的就是 16 GB 机器在「桌面端 + CLI 并发、开满调试信息、thin LTO、单 codegen unit」下被 OOM kill。判断方法不是看内存占用曲线(那时进程已经没了),而是看内核日志里有没有 oom-kill 记录。修法从省内存那一头改:CARGO_BUILD_JOBS=1,再把 CARGO_PROFILE_RELEASE_DEBUG=0、CARGO_PROFILE_RELEASE_LTO=false、CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 一起加上。关 LTO 会影响性能与体积,关调试信息会让崩溃栈变浅——这是明确的代价,不是免费的。
Q4:没有独立显卡能跑吗?
能,但会慢,而且它不会一直提醒你。README 的口径是:有 GPU 时整条 develop 管线跑 wgpu compute kernel(Metal / Vulkan / DX12),24 MP 的 RAW 拖一次滑块约 4 ms(Apple M4 Pro 实测),冷开 2.5 MP 放大视图约 30 ms,全尺寸导出一张约 0.3 秒含并行 JPEG 编码;没有 GPU 时同一条管线跑满所有 CPU 核,只重算滑块影响到的阶段。也就是说功能不缺,缺的是那 4 ms 的响应。真要确认自己走的是哪条路,看启动日志里那一次提示,日志在 Windows 的 %APPDATA%\LightCraft\logs\(上限 16 MiB,超过就不再增长)。
Q5:Web 版能不能直接双击打开 index.html?
不能。官方 docs/web.md 写得很清楚:bundle「can't be opened from file://」,因为 module worker 和 OPFS 都需要 HTTP(S) 源,localhost 与 127.0.0.1 算安全源。所以要么 cargo xtask web --serve 起本地服务,要么丢给任何静态服务器,前提是把 .wasm 以 application/wasm 返回。另外它默认会生成 gzip -9 与 brotli -11 的预压缩副本,生产环境记得配 gzip_static / brotli_static,否则预压缩文件白生成。还有一个容易被忽略的前提:--serve 起的是本地开发服务,只适合自测,别直接拿它对外——它是静态文件服务器,没有并发控制也没有缓存头。想验证「部署后能不能用」,最省事的办法是把 web-site 目录整个拷到一台有 nginx 的机器上,配好 wasm 的 MIME 类型,再用手机连一次,这一步能暴露一半以上的本地测试查不出来的问题。
Q6:这个项目能商用于二次开发吗?许可证到底是 MIT 还是 Apache-2.0?
两个都是。GitHub API 返回的 license 字段是 Apache-2.0,而 README 的徽章与 Cargo.toml 写的是 MIT OR Apache-2.0——这是 Rust 生态常见的双许可,含义是「你可以选其中任意一个遵守」,不是「必须同时满足」。商用前建议把仓库根目录的两个 LICENSE 文件都读一遍,因为 Apache-2.0 比 MIT 多一条专利授权与一条商标限制。另外它的贡献规则里有一条对二开很关键:clean-room,禁止参考 darktable、RawTherapee、LibRaw 这类 GPL 实现的代码——你如果打算把自己的修改回馈上游,这条会约束你的写法。
源码仓库在这:storytold/lightcraft;发布包在 Releases。想先看同类工具的另一条路线(批量压缩而不是显影),站内 squoosh-cli 停更后的三条批量压缩路线 里有实测数据可以对照。

