AR.js NFT图像追踪本地运行正常 部署GitHub Pages报ar-nft.js 404 onError
部署后NFT标记加载404的排查修复方案
- 首先纠正一个常见的误判:控制台抛出的
ar-nft.js 404 onError不是指引入的ar-nft.js脚本本身加载失败——AR.js内部所有资源加载失败的错误,都会统一抛出这个固定提示,和你换不换ar-nft.js的CDN源没有关系。你需要打开开发者工具的Network面板,刷新页面,找到真正标红404的请求地址,顺着路径定位问题。
核心修复点
1. 修正ArToolkit的基础路径
- 你代码里配置的基础路径是相对路径:
THREEx.ArToolkitContext.baseURL = "libs/arJS/" - 本地运行时页面直接在站点根目录下,相对路径可以正常工作;但GitHub Pages的部署站点通常是带仓库名的二级路径结构,相对路径会出现定位偏移,导致AR.js内部加载wasm识别程序、相机参数文件时找不到目标。
- 把这个值改成带仓库名的绝对路径,末尾必须保留斜杠:
THREEx.ArToolkitContext.baseURL = "/[你的GitHub仓库名]/libs/arJS/"
2. 修正NFT描述文件的路径配置
- AR.js加载NFT标记时,会按照
descriptorsUrl配置的路径,自动拼接加载三个核心识别文件:.f32、.fset、.fset3,只要其中一个文件路径不对,就会触发加载错误。 - 你代码里当前的配置是:
descriptorsUrl: "assets/dataNFT/coloring3d-bear-small" - 这个路径的问题和上面的baseURL一致,是相对路径,在二级路径的站点下会出现定位偏移。同时需要核对两个容易踩的细节:
- GitHub Pages的服务器是Linux文件系统,对大小写严格敏感,登录你的GitHub仓库,检查
assets/dataNFT/目录下的三个对应文件,是不是文件名大小写完全和配置一致——比如实际文件名是大写开头的Coloring3d-bear-small.f32,配置里写小写的路径就会直接404。 - 核对
camera_para.dat、三个NFT描述文件是不是0字节的空文件——Git在传输自定义后缀的二进制文件时,偶尔会出现上传截断的问题,导致服务器端没有完整文件内容,触发加载错误。
- GitHub Pages的服务器是Linux文件系统,对大小写严格敏感,登录你的GitHub仓库,检查
- 把descriptorsUrl同样改成带仓库名的绝对路径,不要使用相对路径:
descriptorsUrl: "/[你的GitHub仓库名]/assets/dataNFT/coloring3d-bear-small"
内容的提问来源于stack exchange,提问作者pillipillow
相关产品推荐
相关产品推荐

