img2threejs 装完先跑一张最小单图 / 确认依赖、导出与 Three.js 版本都对得上

img2threejs 装完之后，“能启动”和“能交付”是两件事。判断装好没有，最省事的办法是拿一张只有单一主体、纯色背景的小图，走一遍从读图到导出的完整链路，再把导出物塞进一个最小 Three.js 页面里渲染出来。这张图不是用来出效果的，是用来暴露问题的：依赖缺哪个包、导出文件写到哪、贴图路径对不对、Three.js 版本吃不吃这个格式，一轮下来基本都能看到。正式图前先做这一步，比直接上复杂场景再回头排查要省时间。

最小单图验证的放行标准建议按三段看：环境段里运行时版本、包管理器依赖列表、转换入口命令都能正常返回；转换段里进程退出码为 0 且输出目录出现模型文件、场景描述文件和贴图目录；渲染段里 Three.js 页面加载后控制台无 404、无 loader 报错、模型在视口内可见。三段任何一段只过一半，就先不要在正式图上投入，先去定位那一段。适用场景是本地或单机环境首次安装后的自检，涉及远程服务、私有模型权重或自定义导出格式的部分，需要结合各自环境再确认。

选一张只有单一主体、纯色背景的图做基线

基线图的作用是排除输入复杂度对结果的干扰。如果一张图本身有五个物体、背景是木纹桌面、还带反光，那么导出结果不对时，你分不清是工具链问题还是输入太难。选图建议满足下面几条：

画面里只有一个主体，主体轮廓清晰，与背景有明显色差。
背景是纯色或接近纯色，没有渐变、纹理、投影杂物。
边长适中，通常 512 到 1024 像素这一档够用，太小的图细节不足，太大的图会拖长首次运行时间，不好判断是卡住还是在算。
格式用常见的 PNG 或 JPG，色彩模式为 RGB 或 sRGB，8 位通道。
没有水印、文字、边框，没有主体被裁切。

需要排除的图：多主体或主体互相遮挡的图；大面积透明通道的 PNG，透明度在不同导出环节的处理方式不一致，容易造成误判；带方向信息的手机原图（EXIF 旋转），读进来可能是躺倒的；超长宽比的截图或横幅；16 位、CMYK 色彩空间的图；动图格式；带强高光、镜面反射或大面积阴影的实拍图。这些图不是不能用，而是不适合当第一次验证的输入。

检查运行环境与依赖是否齐全

启动失败和中途报错大多来自两处：运行时版本不满足，或者依赖没装全。先跑一组通用检查命令，把版本信息记下来，后面和报错对照时有用。具体命令名以你本机实际安装的入口为准，下面只是骨架：

# 运行时版本
node -v
npm -v
# 或 pnpm -v / yarn -v，取决于你用的包管理器

# 依赖列表是否完整
npm ls `--depth`=0
# 检查是否有 extraneous 或 missing 条目

# 转换工具的入口是否可执行
npx img2threejs `--help`
# 或全局安装后的 img2threejs `--help`

# Three.js 版本，决定后面用哪种加载方式
npm ls three

如果工具链里包含 Python 部分，再补一条 python -V 和对应的依赖导出命令。缺包的报错特征通常很直白：Cannot find module、ERR_MODULE_NOT_FOUND、ModuleNotFoundError: No module named、command not found。带原生模块的依赖还可能卡在编译阶段，报 node-gyp 相关错误或缺 C++ 构建工具。另一类容易被忽略的是版本错配：工具读的是本地的 Three.js，而工程里装的是另一个大版本，导入时才暴露出来。所以这一步建议把 npm ls three 的输出也留一份。

img2threejs 装完先跑一张最小单图 / 确认依赖、导出与 Three.js 版本都对得上

跑一次转换并记录输入输出路径

用绝对路径跑，避免相对路径在子进程里被解析到别处。命令骨架如下，参数名以 `--help` 输出为准：

mkdir -p out/baseline
img2threejs \
  `--input` /abs/path/baseline.png \
  `--output` /abs/path/out/baseline \
  `--verbose`

echo "exit code: $?"
ls -R out/baseline

日志里值得盯的是几行：读图后打印的尺寸和通道数，确认没有被旋转或缩放成意外值；依赖模型或权重是否加载成功，这一行缺了通常意味着后面是空结果；几何生成或网格化的阶段标记，看它是走到了最后一步还是中途停下；导出时写入的具体文件路径。最后一定要看退出码，以及输出目录的实际内容。

输出目录通常会出现这些类型：模型文件（.glb 或 .gltf 加配套的 .bin）、场景或材质描述（.json 或生成的 .js 模块）、贴图目录（textures/ 下的 .png 或 .jpg）。如果进程返回 0 但目录是空的或者只有一个空壳 json，那就是静默失败，先不要往下做渲染验证，先回去看 verbose 日志里断在哪一步。

把输出导入 Three.js 工程验证渲染

渲染验证要放在一个最小工程里，而不是塞进已有项目，否则加载器版本、打包配置这些变量会混进来。如果是 .glb / .gltf，用 GLTFLoader 载入；如果是生成的 js 模块，按模块导出方式直接 import。下面是 glTF 路线的骨架代码，路径和加载器导入方式按你工程实际结构调整：

import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
camera.position.set(2, 2, 4);
camera.lookAt(0, 0, 0);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
scene.add(new THREE.AmbientLight(0xffffff, 1.2));

new GLTFLoader().load('/models/baseline.glb', (gltf) => {
  scene.add(gltf.scene);
  console.log('loaded', gltf.scene.children.length);
}, undefined, (err) => {
  console.error('load failed', err);
});

renderer.setAnimationLoop(() => renderer.render(scene, camera));

贴图路径不对是最常见的失败形态，表现比较固定：浏览器网络面板里出现 404，控制台里加载器报找不到贴图文件，模型能出来但通体是白色或黑色，或者只有几何没有材质。glTF 里的贴图路径是相对 .gltf 文件的，把模型和 textures 目录分开搬动就会断链。另外，如果模型加载后看不见，先检查包围盒尺寸和相机位置是否匹配，别再回头怀疑转换环节。

按三段检查结果决定是否可以上正式图

三段都过，再换正式图。各段的通过条件和失败时的处理方向：

环境段：运行时版本满足工具要求、npm ls 没有 missing 条目、入口命令能正常输出帮助信息、Three.js 版本与加载器用法对得上。失败时先补装依赖或对齐版本，不要急着改输入图。
转换段：退出码为 0，日志走完所有阶段，输出目录里同时存在模型文件、场景描述和贴图目录。失败时先看 verbose 日志定位断点，再确认输入图是否落在了前面列的排除条件里。
渲染段：页面无 404、无加载器报错、模型在视口内可见且带材质。失败时先查贴图相对路径和静态资源服务配置，再查材质是否需要额外环境光或色调映射。

只有三段都稳定复现，才建议把正式图放进来。正式图比基线图多的变量主要在输入复杂度上，所以正式图第一次跑的时候，仍然建议保留同样的输出目录结构和日志开关，方便把新问题归因到输入还是链路。如果某一段在基线图上就有偶发失败，先不要靠重试绕过去，把那个不稳定点记下来，它通常会在正式图上被放大。