MediaPipe Vision WASMをNext.js/Webプロジェクトに導入する環境構築ガイド。@mediapipe/tasks-vision インストール、WASMファイル配置、webpack設定、Turbopack対応。mediapipe wasm setup nextjs webpack environment vision
MediaPipe Vision（ハンドトラッキング、ポーズ推定、顔メッシュ等）をWebAssembly経由でNext.js/Webプロジェクトに導入するための環境構築ガイド。
npm install @mediapipe/tasks-vision
@mediapipe/tasks-vision にHandLandmarker、PoseLandmarker、FaceLandmarker等が統合済み@mediapipe/hands、@mediapipe/pose 等の旧パッケージはレガシーであり、現在は @mediapipe/tasks-vision に統合されている@types/* の追加インストール不要（vision.d.ts が同梱）public/mediapipe/wasm/ ディレクトリにWASMファイルを配置するvision_wasm_internal.jsvision_wasm_internal.wasmvision_wasm_nosimd_internal.js / vision_wasm_nosimd_internal.wasm — SIMD非対応版vision_wasm_module_internal.js / vision_wasm_module_internal.wasm — モジュール版FilesetResolver がブラウザのSIMD対応を自動判定し、適切なWASMを選択するpublic/
mediapipe/
wasm/
vision_wasm_internal.js
vision_wasm_internal.wasm
vision_wasm_nosimd_internal.js
vision_wasm_nosimd_internal.wasm
vision_wasm_module_internal.js
vision_wasm_module_internal.wasm
package.json に以下を追加すると npm install 後に自動でWASMファイルがコピーされる。
{
"scripts": {
"postinstall": "cp -r node_modules/@mediapipe/tasks-vision/wasm public/mediapipe/"
}
}
初回セットアップ時は mkdir -p public/mediapipe を事前に実行すること。
const nextConfig: NextConfig = {
reactStrictMode: true,
turbopack: {}, // Next.js 16+: Turbopackがデフォルト有効、このキーが必須
webpack: (config, { isServer }) => {
if (!isServer) {
config.resolve.fallback = {
...config.resolve.fallback,
fs: false,
path: false,
crypto: false,
};
}
return config;
},
};
@mediapipe/tasks-vision がNode.js APIを参照するため、ブラウザバンドルでは false に設定必須turbopack: {} キーの明示が必須ローカルへのWASMファイル配置の代わりに、CDN経由で FilesetResolver に直接URLを渡すことも可能。
import { FilesetResolver, HandLandmarker } from "@mediapipe/tasks-vision";
const vision = await FilesetResolver.forVisionTasks(
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/wasm"
);
@mediapipe/tasks-vision に vision.d.ts が同梱されており、@types/* の追加インストールは不要PoseLandmarker の型に解決問題が発生する場合は動的importと any キャストで回避する// 型エラーが出る場合の回避策
const { PoseLandmarker, FilesetResolver } = await import(
"@mediapipe/tasks-vision"
) as any;
MediaPipe WASMのロードやカメラAPIはブラウザAPIに依存するため、コンポーネントに "use client" を必ず付与する。
"use client";
import { useEffect, useRef } from "react";
import { FilesetResolver, HandLandmarker } from "@mediapipe/tasks-vision";
const vision = await FilesetResolver.forVisionTasks("/mediapipe/wasm");
const handLandmarker = await HandLandmarker.createFromOptions(vision, {
baseOptions: {
modelAssetPath: "/mediapipe/models/hand_landmarker.task",
},
numHands: 2,
});
| 症状 | 原因 | 対処 |
|---|---|---|
Module not found: Can't resolve 'fs' | webpack fallback未設定 | next.config.ts にfallback設定を追加 |
| WASMファイルが404 | public/mediapipe/wasm/ 未配置 | npm run postinstall を実行 |
| Turbopackビルドエラー | turbopack キー未設定 | next.config.ts に turbopack: {} を追加 |
| 型エラー（PoseLandmarker） | exports mapの型解決問題 | 動的import + any キャストで回避 |
| ハイドレーションエラー | SSRでWASMにアクセスしている | コンポーネントに "use client" を付与 |