Web 图形与 3D / 系统课时

排查构建后 404 与 CORS 错误

排查构建后 404 与 CORS 错误

模型在开发环境可以加载,部署后却出现 404、Failed to fetch 或 CORS 报错。先用浏览器确认失败的实际请求地址、HTTP 响应与资源内容,再分别修正发布路径或跨域响应头,最后通过线上构建产物和模型显示结果验收。

学习目标

  • 利用 Network 和 Console 区分资源 404、错误的 HTML 回退与 CORS 拦截。
  • 修复 Vite 子路径部署及 glTF 外部依赖的资源定位。
  • 检查跨域授权并验证模型在正式环境中加载成功。

从失败请求判断根因

  1. 打开已部署页面,按 F12 进入开发者工具,在 Network 勾选 Disable cache,刷新页面;在筛选栏查找 .glb、.gltf、.bin、纹理文件或解码器文件。
  2. 点击失败请求,记录 Request URL、Status Code、Response Headers 和 Response;同时查看 Console 是否提示 Access-Control-Allow-Origin。
  3. 检查请求是否发往预期域名及部署前缀,不要只看控制台里最后一个 GLTFLoader 异常。
现象 优先检查
404 Not Found 文件是否实际部署、URL 前缀和大小写是否匹配
200 OK,响应为 text/html 静态资源请求是否误入 SPA 的 index.html 回退
请求显示成功但 Console 报 CORS 请求的 Origin 是否被资源服务器的响应头允许
OPTIONS 失败 是否使用了非简单请求头,以及服务器是否正确处理预检

同一次故障可能同时出现 404 和 CORS:例如资源返回 404,错误页又未附带跨域头。应先查清原始 URL 和服务器响应,再修正授权。

GLB 请求的 404、HTML 回退与 CORS 故障定位流程

在 Console 复现实际请求

在浏览器 Console 直接运行下面的完整脚本,把 Network 中模型请求的 Request URL 粘贴到弹窗。它不依赖 Three.js,可先判断浏览器能否读取原始资源。

js
(async () => {
  const url = window.prompt('粘贴模型的 Request URL');
  if (!url) return;

  try {
    // 保留浏览器的跨域检查,不用 no-cors 掩盖错误。
    const response = await fetch(url, { mode: 'cors' });
    console.log(`HTTP ${response.status}, ok=${response.ok}`);
    console.log(`Content-Type: ${response.headers.get('content-type')}`);
  } catch (error) {
    console.log(`请求失败:${error.name}`);
  }
})();

预期输出示例(URL 存在、可读取且服务器标注了 GLB 类型):

text
HTTP 200, ok=true
Content-Type: model/gltf-binary

实际 MIME 也可能是 application/octet-stream;若返回 text/html,应检查是否取到了网页而非模型。404 对应 ok=false;跨域、DNS 或 TLS 失败都可能进入 TypeError 分支,不能仅凭异常名判定 CORS,必须结合 Console 的具体提示。

修正 Vite 发布前缀与资源引用

假设 Vite 应用部署到网站的 /viewer/ 子路径,而模型放在项目的 public/models/robot.glb。Vite 构建后应生成 dist/models/robot.glb,线上访问路径则应是 /viewer/models/robot.glb,不能继续硬编码 /models/robot.glb。路径规则见 Vite 官方文档。

项目根目录的 vite.config.js 可设置为:

js
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/viewer/'
});

配置生效后,Vite 会把构建资源的公共前缀设为 /viewer/。对代码中手工拼接的模型 URL,还需要使用 import.meta.env.BASE_URL。以下为片段示例,需置于安装了 three 的 Vite 应用模块中,并传入已创建的 scene:

js
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

export async function loadRobot(scene) {
  // BASE_URL 在构建时替换为实际部署前缀。
  const url = `${import.meta.env.BASE_URL}models/robot.glb`;
  const gltf = await new GLTFLoader().loadAsync(url);
  scene.add(gltf.scene);
}

预期生效行为:调用 loadRobot(scene) 后,请求目标为 /viewer/models/robot.glb,解析成功后角色节点加入场景。若使用 .gltf 而非独立 .glb,还需核对其相对引用的 .bin、图片文件是否一同发布,文件名大小写是否严格一致;Draco、KTX2 解码依赖的独立资源也应检查。

在资源服务器修复 CORS

只有页面与模型文件的协议、主机名或端口不同才涉及跨源读取限制。以页面源 https://app.example.com、模型放在另一资源域名为例,模型服务器应在实际 GET 响应中返回 Access-Control-Allow-Origin: https://app.example.com,这属于响应头,不能靠前端增加同名请求头解决。

若静态文件由 Nginx 提供,可参考以下片段示例;放入资源站点的 server 配置中,按真实目录和页面源调整:

nginx
location /models/ {
    root /srv/static;
    add_header Access-Control-Allow-Origin "https://app.example.com" always;
}

该示例把 /models/robot.glb 映射到 /srv/static/models/robot.glb。应用配置后先执行 nginx -t 验证语法,再按部署流程重载服务。公开且不携带凭据的资源可以使用 *;若请求携带 Cookie 等凭据,则必须返回明确的允许源及 Access-Control-Allow-Credentials: true,不能使用 *。只有触发预检时,才需进一步检查 OPTIONS 响应允许的方法和请求头;具体规则可查阅 MDN CORS 文档。

重新构建并做线上验收

  1. 在项目根目录执行 npm run build,预期构建成功且 dist/models/robot.glb 存在;把 dist 中的内容部署到网站的 /viewer/ 对应目录。若模型来自独立资源服务器,则确认其部署目录而非只检查前端 dist。
  2. 用正式域名访问页面,在 Network 禁用缓存后刷新,确认 GLB 与引用的 .bin、纹理等都获得有效响应,Request URL 指向正确域名与路径,Response 不是回退 HTML。
  3. 对跨域资源,确认 GET 响应的 Access-Control-Allow-Origin 与页面源匹配,Console 不再出现 CORS 错误,Three.js 场景中能看到模型。
  4. 如更新后仍请求旧 URL,检查 CDN 缓存和已部署的 JS 包版本;不要把允许静态资源的 404 错误交给 SPA 回退页面来伪装成 200。

若 Network 全部正常而模型仍不可见,下一步应检查解析错误、解码器及场景相机位置,而不是继续修改 CORS 响应头。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查构建后 404 与 CORS 错误

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

登录哪都通