Next.js 中无法加载 face-api.js 模型（如 ssd_mobilenetv1）通常源于路径解析错误——服务端环境不支持 fs 且静态资源必须通过 HTTP URI 访问，而非本地文件路径。本文详解如何将模型部署至 public/ 目录，并使用 loadFromUri 安全加载。
next.js 中无法加载 face-api.js 模型（如 `ssd_mobilenetv1`）通常源于路径解析错误——服务端环境不支持 `fs` 且静态资源必须通过 http uri 访问，而非本地文件路径。本文详解如何将模型部署至 `public/` 目录，并使用 `loadfromuri` 安全加载。
在 Next.js 应用中集成 face-api.js 进行前端人脸检测时，一个常见误区是直接复用 Node.js 环境下的文件系统（fs）逻辑或相对路径调用（如 load('/model')）。由于 Next.js 的混合渲染特性（SSR/SSG/CSR），*服务端组件或 getServerSideProps 中无法访问 fs，且 `faceapi.nets..load()默认尝试解析为绝对 URL，而非静态资源路径**，从而抛出类似Failed to parse URL from /model/ssd_mobilenetv1_model-weights_manifest.json` 的运行时错误。
✅ 正确做法：通过 HTTP URI 加载 public 下的模型
Next.js 将 public/ 目录作为静态资源根目录，所有其中的文件均可通过 / 开头的路径被浏览器直接请求（例如 http://localhost:3000/model/tiny_face_detector_model-weights_manifest.json）。因此，必须使用 loadFromUri() 并传入可公开访问的完整 URI 字符串。
1. 确保模型文件结构正确
将 face-api.js 所需模型文件（.json + .bin）统一放入项目根目录下的 public/model/：
your-nextjs-app/ ├── public/ │ └── model/ │ ├── ssd_mobilenetv1_model-weights_manifest.json │ ├── ssd_mobilenetv1_model.bin │ ├── tiny_face_detector_model-weights_manifest.json │ └── tiny_face_detector_model.bin ├── src/ │ └── app/ │ └── page.tsx
⚠️ 注意：不要在代码中使用 fs.existsSync() —— 它在浏览器端不可用，在服务端则无法访问 public/（该目录仅对客户端 HTTP 请求生效）。
2. 使用 loadFromUri 并动态构造基础路径
为适配不同部署环境（本地开发、Vercel、自定义域名），推荐通过环境变量注入基础 URL：
// .env.local NEXT_PUBLIC_BASE_PATH=http://localhost:3000 # 生产环境示例（Vercel）： # NEXT_PUBLIC_BASE_PATH=https://your-app.vercel.app
// lib/faceApiLoader.ts
import * as faceapi from 'face-api.js';
export async function loadFaceApiModels(): Promise<void> {
// ✅ 安全获取客户端可访问的基础路径
const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
const modelUrl = `${basePath}/model`;
console.log('Loading models from:', modelUrl);
try {
// ✅ 使用 loadFromUri（非 load），确保走 fetch 请求
await faceapi.nets.ssdMobilenetv1.loadFromUri(modelUrl);
await faceapi.nets.tinyFaceDetector.loadFromUri(modelUrl);
await faceapi.nets.faceLandmark68Net.loadFromUri(modelUrl);
await faceapi.nets.faceRecognitionNet.loadFromUri(modelUrl);
console.log('✅ All face-api.js models loaded successfully');
} catch (err) {
console.error('❌ Failed to load face-api.js models:', err);
throw err;
}
}3. 在客户端组件中调用（务必在浏览器环境）
由于 face-api.js 依赖 canvas 和 fetch，必须在 useEffect 或事件处理器中执行加载逻辑，且确保组件已挂载到 DOM：
// app/page.tsx
'use client';
import { useEffect } from 'react';
import { loadFaceApiModels } from '@/lib/faceApiLoader';
export default function HomePage() {
useEffect(() => {
// ✅ 只在客户端执行模型加载
loadFaceApiModels().catch(console.error);
}, []);
return <div className="p-4">Face detection ready.</div>;
}? 补充说明与最佳实践
- 避免 load()，始终用 loadFromUri()：load() 内部会尝试自动补全路径，易在 Next.js 中误判为服务端路径；loadFromUri() 明确要求传入有效 URI，行为更可控。
- CORS 注意事项：若模型托管在外部 CDN，请确保响应头包含 Access-Control-Allow-Origin: *，否则浏览器将拦截请求。
- 性能优化建议：可结合 React.lazy + Suspense 实现模型加载状态反馈，或预加载关键模型（如 tinyFaceDetector）以提升首帧检测体验。
- TypeScript 提示：确保已安装类型声明：npm install --save-dev @types/face-api.js。
遵循以上步骤，即可彻底解决 Next.js 中 face-api.js 模型加载失败问题，实现稳定、可部署的人脸识别功能。
