M1 Mac 安装 node-canvas 失败求助：CoreText/CoreText.h 文件缺失

问题原因 #

找不到CoreText/CoreText.h是因为Nix默认隔离了系统框架，而CoreText是macOS原生框架，node-gyp编译时无法自动定位该头文件；同时canvas@2.10.1的预编译二进制包不支持M1架构+Node.js 18的组合，导致回退源码编译时出错。

解决步骤 #

1. 修改Nix Shell配置，引入系统CoreText框架 #

更新你的shell.nix配置，添加darwin SDK的CoreText框架依赖，并设置环境变量让编译器找到系统头文件：

{ pkgs ? import <nixpkgs> {} }:
with pkgs;

stdenv.mkDerivation {
  name = "myproject";

  nativeBuildInputs = [ pkg-config nodePackages.node-gyp ];
  
  buildInputs = [
    nodejs-18_x
    yarn
    jdk
    docker
    chromedriver
    rustup
    libuuid
    act
    cairo
    pango
    libpng
    llvm
    librsvg
    pixman
    giflib
    libjpeg
    # 添加macOS原生框架依赖
    darwin.apple_sdk.frameworks.CoreText
    darwin.apple_sdk.frameworks.ApplicationServices
  ];

  # 配置环境变量，让编译器定位系统SDK路径
  shellHook = ''
    export SDKROOT=$(xcrun --show-sdk-path)
    export CPATH="$SDKROOT/usr/include:$CPATH"
    export LIBRARY_PATH="$SDKROOT/usr/lib:$LIBRARY_PATH"
  '';
}

2. 清理缓存后重新安装 #

退出当前Nix Shell，重新进入后清理yarn缓存再执行安装：

nix-shell
yarn cache clean
yarn install

3. 可选：升级canvas版本 #

canvas@2.10.1发布时间较早，对M1和Node.js 18的支持有限。可以尝试升级到最新稳定版（如2.11.x），新版本提供了M1架构的预编译二进制包，能直接跳过源码编译环节：

yarn add canvas@^2.11.0

验证 #

安装完成后，可通过以下代码验证canvas是否正常工作：

const { createCanvas } = require('canvas');
const canvas = createCanvas(200, 200);
const ctx = canvas.getContext('2d');
ctx.fillText('Test', 50, 50);
console.log('Canvas initialized successfully');

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