Node.js/Express环境下无需浏览器生成Minecraft皮肤3D静态图方案问询

以下是无需Puppeteer、基于three.js + 画布模拟库的实现方案，适配TypeScript项目：

核心依赖选择 #

放弃three.js官方Node端的WebGL适配（易出现工具冲突），改用**@napi-rs/canvas**（高性能、TS友好的Node画布库）搭配three.js的WebGLRenderer做渲染。

实现步骤 #

1. 安装依赖 #

npm install three @napi-rs/canvas @types/three express multer

（multer用于处理文件上传，按需添加）

2. 封装Minecraft皮肤渲染工具 #

创建skin-renderer.ts，实现皮肤加载、模型构建和渲染逻辑：

import * as THREE from 'three';
import { createCanvas, loadImage } from '@napi-rs/canvas';

// 构建符合Minecraft皮肤规范的角色模型（完整UV映射）
function createPlayerModel(texture: THREE.Texture): THREE.Group {
  const group = new THREE.Group();
  const mat = new THREE.MeshBasicMaterial({ map: texture, side: THREE.DoubleSide });

  // 头部（UV适配皮肤顶部区域）
  const headGeo = new THREE.BoxGeometry(1, 1, 1);
  adjustHeadUV(headGeo);
  const head = new THREE.Mesh(headGeo, mat);
  head.position.y = 1;
  group.add(head);

  // 身体（UV适配皮肤躯干区域）
  const bodyGeo = new THREE.BoxGeometry(1, 1.5, 0.5);
  adjustBodyUV(bodyGeo);
  const body = new THREE.Mesh(bodyGeo, mat);
  body.position.y = 0;
  group.add(body);

  // 手臂（UV适配皮肤手臂区域）
  const armGeo = new THREE.BoxGeometry(0.3, 1.5, 0.3);
  adjustArmUV(armGeo);
  const leftArm = new THREE.Mesh(armGeo, mat);
  leftArm.position.set(-0.65, 0, 0);
  group.add(leftArm);
  const rightArm = leftArm.clone();
  flipArmUV(rightArm.geometry);
  rightArm.position.set(0.65, 0, 0);
  group.add(rightArm);

  // 腿部（UV适配皮肤腿部区域）
  const legGeo = new THREE.BoxGeometry(0.3, 1.5, 0.3);
  adjustLegUV(legGeo);
  const leftLeg = new THREE.Mesh(legGeo, mat);
  leftLeg.position.set(-0.25, -1.25, 0);
  group.add(leftLeg);
  const rightLeg = leftLeg.clone();
  flipLegUV(rightLeg.geometry);
  rightLeg.position.set(0.25, -1.25, 0);
  group.add(rightLeg);

  return group;
}

// 以下为Minecraft皮肤UV映射调整函数（匹配官方皮肤布局）
function adjustHeadUV(geo: THREE.BoxGeometry) {
  const uvAttribute = geo.getAttribute('uv') as THREE.BufferAttribute;
  // 头部各面UV坐标对应皮肤的8x8区域（顶部）
  const uvMap = [
    // 正面
    8/64, 8/64, 16/64, 8/64, 16/64, 16/64, 8/64, 16/64,
    // 背面
    24/64, 8/64, 32/64, 8/64, 32/64, 16/64, 24/64, 16/64,
    // 顶部
    8/64, 0/64, 16/64, 0/64, 16/64, 8/64, 8/64, 8/64,
    // 底部
    16/64, 0/64, 24/64, 0/64, 24/64, 8/64, 16/64, 8/64,
    // 左侧
    0/64, 8/64, 8/64, 8/64, 8/64, 16/64, 0/64, 16/64,
    // 右侧
    16/64, 8/64, 24/64, 8/64, 24/64, 16/64, 16/64, 16/64
  ];
  uvAttribute.setArray(new Float32Array(uvMap));
  uvAttribute.needsUpdate = true;
}

function adjustBodyUV(geo: THREE.BoxGeometry) {
  const uvAttribute = geo.getAttribute('uv') as THREE.BufferAttribute;
  // 躯干对应皮肤的16-32x8-20区域
  const uvMap = [
    20/64, 20/64, 28/64, 20/64, 28/64, 32/64, 20/64, 32/64,
    36/64, 20/64, 44/64, 20/64, 44/64, 32/64, 36/64, 32/64,
    20/64, 16/64, 28/64, 16/64, 28/64, 20/64, 20/64, 20/64,
    28/64, 16/64, 36/64, 16/64, 36/64, 20/64, 28/64, 20/64,
    16/64, 20/64, 20/64, 20/64, 20/64, 32/64, 16/64, 32/64,
    44/64, 20/64, 48/64, 20/64, 48/64, 32/64, 44/64, 32/64
  ];
  uvAttribute.setArray(new Float32Array(uvMap));
  uvAttribute.needsUpdate = true;
}

// 其余手臂、腿部UV调整函数可参考头部/躯干逻辑，匹配Minecraft皮肤规范，此处省略实现

// 渲染皮肤为Base64图片
export async function renderSkinToBase64(skinSource: string | Buffer): Promise<string> {
  // 创建模拟画布
  const canvas = createCanvas(512, 512);
  const renderer = new THREE.WebGLRenderer({
    canvas: canvas as unknown as HTMLCanvasElement,
    alpha: true,
    antialias: true
  });
  renderer.setSize(512, 512);
  renderer.setClearColor(0x000000, 0);

  // 初始化场景与相机
  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
  camera.position.set(3, 2, 3);
  camera.lookAt(0, 0, 0);

  // 加载皮肤贴图
  const skinImage = typeof skinSource === 'string' ? await loadImage(skinSource) : await loadImage(skinSource);
  const texture = new THREE.CanvasTexture(skinImage as unknown as HTMLCanvasElement);
  texture.needsUpdate = true;

  // 添加角色模型与灯光
  const playerModel = createPlayerModel(texture);
  scene.add(playerModel);
  scene.add(new THREE.AmbientLight(0xffffff, 0.8));
  scene.add(new THREE.DirectionalLight(0xffffff, 0.5).position.set(5, 5, 5));

  // 渲染并转Base64
  renderer.render(scene, camera);
  return canvas.toDataURL('image/png');
}

3. 在Express接口中集成 #

创建Express路由skin-routes.ts：

import express from 'express';
import multer from 'multer';
import { renderSkinToBase64 } from './skin-renderer';

const router = express.Router();
const upload = multer({ dest: './temp-skins/' });

// 通过本地文件路径生成皮肤图片
router.get('/generate', async (req, res) => {
  try {
    const skinPath = req.query.path as string;
    if (!skinPath) return res.status(400).send('缺少皮肤文件路径');
    
    const base64Image = await renderSkinToBase64(skinPath);
    res.send({ image: base64Image });
  } catch (err) {
    console.error(err);
    res.status(500).send('生成皮肤图片失败');
  }
});

// 上传皮肤文件后生成图片
router.post('/upload', upload.single('skin'), async (req, res) => {
  try {
    if (!req.file) return res.status(400).send('未上传皮肤文件');
    
    const base64Image = await renderSkinToBase64(req.file.path);
    res.send({ image: base64Image });
  } catch (err) {
    console.error(err);
    res.status(500).send('生成皮肤图片失败');
  }
});

export default router;

4. 关键注意事项 #

• 完整UV映射：若需要完全匹配Minecraft官方皮肤细节，需补全手臂、腿部的UV调整函数，可参考官方皮肤布局文档。
• 性能优化：对相同皮肤的请求做缓存，避免重复渲染；渲染完成后清理临时上传文件。
• TypeScript配置：确保tsconfig.json中module设为CommonJS或ESNext，开启esModuleInterop，解决模块导入冲突。
• 依赖冲突：卸载之前可能安装的three.js Node端第三方适配包，仅保留官方three包与@napi-rs/canvas。

内容的提问来源于stack exchange，提问作者Yggdrazil