MediaPipe Web 端接入实战：从 CDN 到工程化落地

运行测试

不能直接双击 HTML 文件打开，浏览器会限制本地文件的摄像头权限。必须通过 HTTP 服务打开：

1. Python 简易服务：在终端进入 HTML 目录执行 python -m http.server 8080，访问 http://localhost:8080。
2. VS Code 插件：安装「Live Server」插件，右键 HTML 文件选择「Open with Live Server」。

运行成功后授权摄像头，即可看到实时手部追踪效果。

关键代码说明

• modelAssetPath：模型路径，生产环境建议下载到本地托管，避免 CDN 失效。
• runningMode：运行模式，按需切换 VIDEO（视频流）、LIVE_STREAM（低延迟）、IMAGE（静态图片）。
• delegate：设置为 'GPU' 优先使用 GPU 加速，性能提升明显，不支持则自动降级为 CPU。
• drawingUtils：封装的绘图工具，无需手写 Canvas 逻辑。

方式 2：npm 包接入

适合 Vue、React、Angular 等框架项目，便于管理和维护。以下以 React 为例。

安装依赖

终端执行以下命令安装核心依赖：

npm install @mediapipe/camera_utils @mediapipe/hand_landmarker @mediapipe/drawing_utils
# 如需其他功能，替换对应包名
# 人体姿态估计：npm install @mediapipe/pose_landmarker
# 人脸关键点检测：npm install @mediapipe/face_landmarker

React 组件示例

创建 MediaPipeHandTracker.jsx 组件：

import React, { useRef, useEffect } from 'react';
import { Camera } from '@mediapipe/camera_utils';
import { HandLandmarker, HAND_CONNECTIONS } from '@mediapipe/hand_landmarker';
import { drawConnectors, drawLandmarks } from '@mediapipe/drawing_utils';

const MediaPipeHandTracker = ({ width = 640, height = 480 }) => {
    const videoRef = useRef(null);
    const canvasRef = useRef(null);
    let camera = null;
    let handLandmarker = null;

    useEffect(() => {
        const initMediaPipe = async () => {
            handLandmarker = new HandLandmarker({
                baseOptions: {
                    modelAssetPath: '/models/hand_landmarker.task',
                    delegate: 'GPU'
                },
                numHands: 2,
                runningMode: 'VIDEO'
            });

            const onResults = (results) => {
                const canvasCtx = canvasRef.current?.getContext('2d');
                if (!canvasCtx) return;
                canvasCtx.save();
                canvasCtx.clearRect(0, 0, width, height);
                canvasCtx.drawImage(results.image, 0, 0, width, height);

                if (results.landmarks) {
                    results.landmarks.forEach(landmarks => {
                        drawConnectors(canvasCtx, landmarks, HAND_CONNECTIONS, { color: '#00FF00', lineWidth: 2 });
                        drawLandmarks(canvasCtx, landmarks, { color: '#FF0000', lineWidth: 1, radius: 2 });
                    });
                }
                canvasCtx.restore();
            };

            if (videoRef.current) {
                camera = new Camera(videoRef.current, {
                    onFrame: async () => {
                        await handLandmarker.detectAsync(videoRef.current, onResults);
                    },
                    width, height
                });
                await camera.start();
            }
        };

        initMediaPipe();

        return () => {
            if (camera) camera.stop();
            if (handLandmarker) handLandmarker.close();
        };
    }, [width, height]);

    return (
        <div style={{ position: 'relative', width, height, margin: '0 auto', border: '1px solid #eee' }}>
            <video ref={videoRef} style={{ position: 'absolute', top: 0, left: 0, display: 'none' }} autoPlay muted playsInline />
            <canvas ref={canvasRef} width={width} height={height} />
        </div>
    );
};

export default MediaPipeHandTracker;

组件使用

在页面组件中引入：

import React from 'react';
import MediaPipeHandTracker from './MediaPipeHandTracker';

const App = () => {
    return (
        <div style={{ padding: '20px' }}>
            <h2>React + MediaPipe 手部追踪演示</h2>
            <MediaPipeHandTracker width={640} height={480} />
        </div>
    );
};

export default App;

Vue 项目适配

Vue 项目逻辑一致，只需将 React 的 useRef、useEffect 替换为 Vue 的 ref、onMounted、onUnmounted。

<template>
    <div>
        <video ref="video" autoplay muted playsinline></video>
        <canvas ref="canvas" :width="width" :height="height"></canvas>
    </div>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { Camera } from '@mediapipe/camera_utils';
import { HandLandmarker, HAND_CONNECTIONS } from '@mediapipe/hand_landmarker';
import { drawConnectors, drawLandmarks } from '@mediapipe/drawing_utils';

const width = ref(640);
const height = ref(480);
const video = ref(null);
const canvas = ref(null);
let camera = null;
let handLandmarker = null;

onMounted(async () => {
    // 复制 React 中的 initMediaPipe 逻辑，替换 ref 调用即可
    // 例：videoRef.current → video.value
});

onUnmounted(() => {
    if (camera) camera.stop();
    if (handLandmarker) handLandmarker.close();
});
</script>

常见问题与解决方案

问题 1：摄像头授权失败

• 本地开发：必须通过 HTTP 服务打开（localhost），不能直接双击。
• 线上部署：必须使用 HTTPS 协议。
• 设备检查：确认设备有可用摄像头，关闭其他占用应用。

问题 2：页面卡顿、帧率低

• 开启 GPU 加速：确保 delegate 设置为 'GPU'。
• 降低分辨率：调整为 480x360，减少计算量。
• 复用实例：避免频繁创建/销毁实例。
• 优化渲染：无需绘制时注释相关代码。

问题 3：模型加载失败

• CDN 方式：检查 modelAssetPath 链接是否有效。
• npm 方式：将模型文件下载到项目 public 目录下，确保路径正确。

问题 4：组件卸载后摄像头仍在运行

• 必须在组件卸载时调用 camera.stop() 和 handLandmarker.close() 释放资源。

功能扩展

MediaPipe 支持多种视觉功能，替换对应依赖包和模型文件即可：

核心 API 速查

• Landmarker 类：
  • detectAsync(image, callback)：异步检测。
  • close()：释放模型资源。
• Camera 类：
  • start()：启动摄像头。
  • stop()：停止摄像头。
  • onFrame：每帧触发回调。
• drawing_utils 工具：
  • drawConnectors(...)：绘制连接线。
  • drawLandmarks(...)：绘制关键点。

总结

本文详细讲解了 MediaPipe SDK 前端项目的两种接入方式。新手或原型开发优先选择 CDN 快速接入，工程化项目选择 npm 包接入。生产环境需注意模型文件本地托管、线上部署使用 HTTPS、优先开启 GPU 加速以及妥善处理异常场景。