Node.js需独立安装而非VSCode自带，90%启动失败源于安装路径、环境变量或版本冲突；必须手动下载LTS版、验证终端识别、配置launch.json才能调试。
VSCode终端里node命令能用，但require('canvas')报错
根本不是Canvas没装对，而是Node-Canvas依赖系统级图形库（如cairo、pango、jpeg），这些库在VSCode终端里找不到——尤其macOS上Homebrew装的库路径默认不被继承。
- 先确认系统级依赖是否就位：
brew install cairo pango libjpeg-glib（macOS）；sudo apt-get install libcairo2-dev libpango1.0-dev libjpeg-dev（Ubuntu） - VSCode终端启动时没加载shell配置，导致
pkg-config路径失效：关掉所有VSCode窗口，终端执行source ~/.zshrc后再用code命令启动 - 安装Canvas必须指定平台和架构：
npm install canvas --build-from-source --platform=linux --arch=x64（Linux服务器）或npm install canvas --build-from-source（本地开发） - Windows用户注意：Node-Canvas 2.10+已弃用prebuilt二进制，必须用Windows Build Tools + Python 3.10，并在npm install前执行
npm config set python "C:\Python310\python.exe"
高斯模糊计算卡顿，process.cpuUsage()显示单核100%
Canvas的ctx.filter = 'blur(5px)'是浏览器API，服务端不能用；Node-Canvas里得手写卷积核，但默认实现是同步阻塞的，会拖垮整个Event Loop。
- 别用
canvas.toBuffer()后直接做模糊——先用canvas.getContext('2d').getImageData()取像素，再用worker_threads分块处理 - 简单提速方案：把图像缩放到1/4尺寸做模糊，再用
ctx.drawImage()放大回原尺寸，视觉损失小但CPU占用降70%+ - 真正高并发场景下，用
cluster模块起多进程，每个子进程独占一个Canvas实例，避免共享内存竞争 - 别在
http.createServer回调里new Canvas()——Canvas构造开销大，应预创建并池化复用
调试时断点进不去Canvas内部方法
Node-Canvas是C++ addon，V8调试器默认不加载其源码映射，F5调试时直接跳过ctx.putImageData()这类调用。
- launch.json里加
"runtimeArgs": ["--inspect-brk"]，然后用Chrome DevTools连chrome://inspect，选中对应进程才能看到底层调用栈 - 想查内存泄漏？在
process.on('exit')里打印canvas.getBuffer().length，确认每次操作后buffer是否被释放 - VSCode调试器对TypedArray支持弱，
imageData.data显示为Uint8ClampedArray [Object]——右键“Debug in Console”才能展开看真实像素值
部署到Linux服务器后Canvas渲染空白或颜色异常
不是代码问题，是服务器没装headless图形环境，Canvas初始化失败却静默吞掉错误。
- 启动前加环境变量：
export DISPLAY=:99 && xvfb-run -a node server.js（xvfb虚拟帧缓冲） - 更轻量方案：用
canvas.createCanvas(0, 0)触发初始化，捕获process.on('uncaughtException')里err.message.includes('Could not load')来判断缺失依赖 - Docker部署时，基础镜像别用
node:alpine——musl libc不兼容Canvas预编译二进制，换node:18-slim并apt装依赖 - 生产环境务必加fallback：当
require('canvas')失败时，降级用纯JS实现的fast-blur包处理小图，避免整个服务挂掉
