Web 图形与 3D / 系统课时
部署后模型路径错误怎么排查
部署后模型路径错误怎么排查
本地开发时展品正常,部署到站点子目录后却出现空白画面、模型请求 404 或 Draco 解码失败,通常是资源 URL 与部署目录不一致。下面以 Vite 项目发布在 /showroom/ 为例,完成生产构建、请求定位、路径修正和桌面及移动端验收。
学习目标
- 正确配置 Vite 的
base,让模型与解码器落在预期的发布路径。 - 利用浏览器 Network 和 Console 区分文件缺失、错误回退与解码失败。
- 用生产构建复测,并在电脑和手机上检查加载、交互及性能。
对齐部署目录与 Vite base
先确定页面实际入口:本例的站点前缀是 /showroom/,服务器必须把构建产物 dist/index.html 映射到 /showroom/,而不是 /showroom/dist/。如果站点直接部署在域名根目录,base 应改为 /。
在项目根目录创建或修改 vite.config.js:
import { defineConfig } from 'vite';
export default defineConfig({
// 生产站点位于子路径;根站点应设为 '/'
base: '/showroom/',
});生效行为:Vite 构建时会处理入口脚本和经构建管线引用的资源路径,但不会自动修正业务代码里手写的 '/models/product.glb'。后者仍从域名根目录请求,容易在子目录部署时返回 404。
把模型放入 public/models/product.glb。Vite 会原样复制它到 dist/models/product.glb,部署后应通过 /showroom/models/product.glb 访问。不要在 URL 中写 public/ 或 dist/;Linux 静态服务器还会区分文件名大小写,例如 Product.glb 与 product.glb 并不等价。
用统一基础路径加载模型
下面是已有 Vite + Three.js 工程的完整 src/main.js 示例。前提是入口 index.html 已引入 /src/main.js、安装了 three,且 public/models/product.glb 是有效模型;若模型使用 Draco 压缩,再把当前安装版本 node_modules/three/examples/jsm/libs/draco/ 内的解码文件复制到 public/draco/。
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf3f6f8);
scene.add(new THREE.HemisphereLight(0xffffff, 0x555555, 2));
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
camera.position.set(2, 1.5, 3);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
// BASE_URL 由 Vite 的 base 配置确定,开发和构建共用这一处。
const base = import.meta.env.BASE_URL;
const draco = new DRACOLoader();
draco.setDecoderPath(`${base}draco/`);
const loader = new GLTFLoader();
loader.setDRACOLoader(draco);
loader.load(
`${base}models/product.glb`,
(gltf) => {
scene.add(gltf.scene);
console.log('模型加载完成');
},
undefined,
(error) => console.error('模型加载失败', error)
);
renderer.setAnimationLoop(() => renderer.render(scene, camera));
window.addEventListener('resize', () => {
camera.aspect = innerWidth / innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(innerWidth, innerHeight);
});预期结果:有效模型解析成功后,Console 出现 模型加载完成,Network 中模型请求指向 /showroom/models/product.glb 且返回 200;模型能否进入画面还取决于其尺寸、原点和相机位置。未使用 Draco 压缩的模型不会因配置了 DRACOLoader 就必须下载解码文件。
按 Network 响应定位真正故障
在已部署页面按 F12 打开 Chrome/Edge 开发者工具,进入 Network,勾选 Disable cache 后刷新。按文件名筛选 product.glb、draco、.bin、.png 或 .ktx2,逐个查看 Headers → Request URL、状态码和 Response。不要只看状态 200:单页应用的回退规则可能把本应返回二进制模型的请求错误地返回 index.html。

| 观察到的现象 | 优先修复位置 |
|---|---|
product.glb 返回 404 |
看 Request URL 是否漏了 /showroom/,再核对构建产物、发布目录和大小写。 |
| 模型请求 200,但响应是 HTML | 服务器把静态资源错误回退到 index.html;让存在的资源文件优先由静态服务命中。 |
模型成功下载,draco_decoder.wasm 或包装脚本 404 |
确认 dist/draco/ 下有对应文件,并让 setDecoderPath 指向 /showroom/draco/。 |
.gltf 加载后 .bin 或贴图 404 |
按 .gltf 中的相对 URI 保留文件夹结构,检查文件名与字符大小写。 |
| 外部资源请求被 CORS 或 403 拦截 | 检查资源服务器的访问权限和跨域响应头;不能只修改前端加载器。 |
若 Console 提示 KHR_texture_basisu 或缺少 KTX2 加载器,则应单独配置 KTX2Loader 及其 Basis 转码器;Draco 只解决对应的网格压缩,并不能解码 KTX2 纹理。请求全部成功却仍看不到模型时,再检查模型包围盒、相机远近裁剪面、光照与 WebGL 错误,避免把渲染问题误判为路径问题。
重建发布并完成双端验收
确认 package.json 已有 Vite 的 build、preview 脚本,在项目根目录执行:
npm run build
npm run preview -- --host 0.0.0.0预期结果:构建成功并生成 dist/index.html、dist/models/product.glb;若使用 Draco,dist/draco/draco_decoder.wasm 等解码文件也应存在。终端会打印预览地址及实际端口,端口可能不同。vite preview 只用于验证构建产物,不是生产 Web 服务器;正式发布的是 dist 内的文件。
在电脑打开预览地址对应的 /showroom/,确认模型请求和解码依赖均成功。手机与电脑连接同一可信局域网,用终端显示的 Network 地址并附加 /showroom/ 访问;只在局域网测试时开启 --host 0.0.0.0,不要直接暴露到公网。
验收时至少检查三件事:首次加载和强制刷新后模型均出现;鼠标旋转、缩放及手机单指拖动、双指缩放能正常操作;开启 Network 的慢速网络模拟后,加载失败能提示错误而不是长期空白,手机连续交互约 30 秒不出现明显冻结。发布后再在真实站点复查一次 Request URL,避免本地预览正确而 CDN 或服务器映射仍错误。