Next.js集成Fabric.js遇canvas.node解析错误求解决方案

问题概述 #

执行npm install fabric后在Next.js中集成Fabric Canvas，出现二进制文件解析错误，已尝试配置next.config.js但未解决。相关错误信息、组件代码及原配置如下：

错误信息 #

./node_modules/canvas/build/Release/canvas.node
Module parse failed: Unexpected character '�' (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file.
(Source code omitted for this binary file)

组件代码 #

import React, { useState, useEffect } from 'react';
import { fabric } from 'fabric';
const designspace = () => {
  const [canvas, setCanvas] = useState('');
  useEffect(() => {
    setCanvas(initCanvas());
  }, []);
  const initCanvas = () => (
    new fabric.Canvas('canvas', {
      height: 800,
      width: 800,
      backgroundColor: 'pink'
    })
  )


  return(
    <div>
      <h1>Fabric.js on React - fabric.Canvas('...')</h1>
      <canvas id="canvas" />
    </div>
  );
};

export default designspace; 

原next.config.js配置 #

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
  },
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
}

module.exports = nextConfig 

错误原因 #

1. SSR兼容性冲突：Fabric依赖浏览器端Canvas API，Next.js默认服务端渲染（SSR）环境无该API，且会尝试加载Node端的canvas.node二进制文件，Webpack无法解析这类文件。
2. Next.js配置规范错误：原配置直接在nextConfig中添加module.rules不符合Next.js的Webpack配置逻辑，需通过专属配置函数修改规则。

解决步骤 #

步骤1：调整组件代码，仅在客户端加载Fabric #

Fabric只能在浏览器环境运行，需避免服务端渲染时加载，可通过两种方式实现：

方案一：用Next.jsdynamic导入禁用SSR

创建主组件文件：

import React from 'react';
import dynamic from 'next/dynamic';

// 动态导入Fabric组件，禁用服务端渲染
const DesignSpaceClient = dynamic(() => import('./designspace-client'), { ssr: false });

const DesignSpace = () => {
  return <DesignSpaceClient />;
};

export default DesignSpace;

创建designspace-client.js文件：

import React, { useState, useEffect } from 'react';
import { fabric } from 'fabric';

const DesignSpaceClient = () => {
  const [canvas, setCanvas] = useState(null);

  useEffect(() => {
    const initCanvas = () => {
      return new fabric.Canvas('canvas', {
        height: 800,
        width: 800,
        backgroundColor: 'pink'
      });
    };

    const newCanvas = initCanvas();
    setCanvas(newCanvas);

    // 组件卸载时清理Canvas实例
    return () => newCanvas.dispose();
  }, []);

  return (
    <div>
      <h1>Fabric.js on React - fabric.Canvas('...')</h1>
      <canvas id="canvas" />
    </div>
  );
};

export default DesignSpaceClient;

方案二：在useEffect中动态导入Fabric

直接修改原组件：

import React, { useState, useEffect } from 'react';

const designspace = () => {
  const [canvas, setCanvas] = useState(null);

  useEffect(() => {
    // 仅在客户端动态加载Fabric
    import('fabric').then(({ fabric }) => {
      const newCanvas = new fabric.Canvas('canvas', {
        height: 800,
        width: 800,
        backgroundColor: 'pink'
      });
      setCanvas(newCanvas);

      return () => newCanvas.dispose();
    });
  }, []);

  return(
    <div>
      <h1>Fabric.js on React - fabric.Canvas('...')</h1>
      <canvas id="canvas" />
    </div>
  );
};

export default designspace;

步骤2：修正next.config.js配置 #

通过Next.js的Webpack配置函数，排除服务端对Fabric的解析，或添加二进制文件处理规则：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
  },
  webpack: (config, { isServer }) => {
    // 服务端编译时跳过Fabric，避免加载Node端二进制文件
    if (isServer) {
      config.externals.push('fabric');
    }

    // 可选：添加二进制文件解析规则，需先安装raw-loader
    config.module.rules.push({
      test: /\.node$/,
      use: 'raw-loader',
    });

    return config;
  },
};

module.exports = nextConfig;

若使用raw-loader，需先安装依赖：

npm install raw-loader --save-dev

步骤3：重置依赖并验证 #

删除缓存文件后重新安装依赖，启动项目验证：

rm -rf node_modules .next
npm install
npm run dev

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