@vercel/ncc Wiki

本地开发环境搭建

前置要求

工具版本要求用途
Node.js22+运行时
pnpm10.33.0+包管理器（通过 corepack）
Python3.14+node-gyp 构建原生模块
node-gyp全局安装编译原生扩展

macOS 额外依赖

brew install pkg-config cairo pango libpng jpeg giflib librsvg

这些是 canvas 原生模块的编译依赖。

Linux (Ubuntu/Debian) 额外依赖

sudo apt install -y libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev librsvg2-dev

快速开始

# 1. 启用 pnpm（通过 corepack）
corepack enable pnpm

# 2. 安装依赖
pnpm install --frozen-lockfile

# 3. 构建原生测试模块（可选，仅用于 binary 测试）
pnpm build-test-binary

# 4. 构建 ncc
pnpm build

# 5. 运行测试
pnpm test

项目脚本

脚本命令说明
buildnode scripts/build.js自举构建 ncc
build-test-binarycd test/binary && node-gyp rebuild && cp ...构建测试用原生模块
testnode --expose-gc --max_old_space_size=4096 jest运行测试
test-coverage同上 + --coverage带覆盖率的测试
prepublishOnlynode scripts/build.js --no-cache发布前无缓存构建

开发工作流

修改源码后测试

# 1. 重新构建
pnpm build

# 2. 运行测试（测试默认使用 dist/ 中的编译产物）
pnpm test

# 3. 或直接测试源码（coverage 模式跳过 dist/）
pnpm test-coverage

调试单个测试

# 运行特定集成测试
node --expose-gc node_modules/jest/bin/jest.js --testPathPattern integration

# 运行 CLI 测试
node --expose-gc node_modules/jest/bin/jest.js --testPathPattern cli

手动测试 ncc

# 使用 dist/ 中的 ncc 编译文件
node dist/ncc/cli.js build ./some-file.js -o /tmp/out

# 直接使用源码（开发时）
node src/cli.js build ./some-file.js -o /tmp/out

注意事项

  • 测试需要 --expose-gc（部分测试手动触发 GC）和 --max_old_space_size=4096（处理大型包如 twilio）
  • pnpm-workspace.yaml 中配置了 onlyBuiltDependencies: [canvas, nan, sharp]，只有这三个包会运行 postinstall 构建脚本
  • 如果 canvas 构建失败，可以忽略（只影响 canvas 相关的集成测试）