Web 图形与 3D / 系统课时

部署后模型路径错误怎么排查

部署后模型路径错误怎么排查

本地开发时展品正常,部署到站点子目录后却出现空白画面、模型请求 404 或 Draco 解码失败,通常是资源 URL 与部署目录不一致。下面以 Vite 项目发布在 /showroom/ 为例,完成生产构建、请求定位、路径修正和桌面及移动端验收。

学习目标

  • 正确配置 Vite 的 base,让模型与解码器落在预期的发布路径。
  • 利用浏览器 Network 和 Console 区分文件缺失、错误回退与解码失败。
  • 用生产构建复测,并在电脑和手机上检查加载、交互及性能。

对齐部署目录与 Vite base

先确定页面实际入口:本例的站点前缀是 /showroom/,服务器必须把构建产物 dist/index.html 映射到 /showroom/,而不是 /showroom/dist/。如果站点直接部署在域名根目录,base 应改为 /。

在项目根目录创建或修改 vite.config.js:

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/。

js
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 脚本,在项目根目录执行:

bash
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 或服务器映射仍错误。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

部署后模型路径错误怎么排查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通