@vercel/ncc Wiki

仓库结构总览

顶层目录

ncc/
├── src/                    # 源代码（核心实现）
│   ├── cli.js              # CLI 入口
│   ├── index.js            # 核心编译引擎（API 入口）
│   ├── typescript.js       # TypeScript 版本解析
│   ├── @@notfound.js       # 未找到模块的运行时占位
│   ├── loaders/            # Webpack Loader 集合
│   └── utils/              # 工具函数
├── dist/                   # 编译产物（发布到 npm 的内容）
│   └── ncc/
│       ├── cli.js          # 编译后的 CLI
│       ├── index.js        # 编译后的核心引擎
│       ├── typescript.js   # TypeScript 解析（原样复制）
│       ├── loaders/        # 编译后的 Loader
│       └── buildin/        # 内建模块
├── scripts/                # 构建脚本
│   └── build.js            # 自举构建脚本
├── test/                   # 测试文件
│   ├── cli.js              # CLI 测试用例定义
│   ├── cli.test.js         # CLI 测试运行器
│   ├── integration.test.js # 集成测试运行器
│   ├── integration/        # 集成测试用例（每个 npm 包一个文件）
│   ├── fixtures/           # 测试固件
│   ├── binary/             # 原生模块测试
│   └── unit/               # 单元测试
├── examples/               # 使用示例
│   ├── hello-world/        # 基础示例
│   ├── multiple-bundles/   # 多入口构建
│   ├── programmatic/       # 编程式 API 使用
│   └── typescript/         # TypeScript 示例
├── patches/                # pnpm patch 文件
├── publish/                # 发布辅助工具
├── .github/workflows/      # CI/CD 配置
├── package.json            # 项目元数据与脚本
├── pnpm-workspace.yaml     # pnpm workspace 配置
├── jest.config.js          # Jest 测试配置
└── release.config.js       # semantic-release 配置

关键文件说明

源代码核心 (src/)

文件行数职责
src/index.js~680核心编译引擎，配置 Webpack 并处理输出
src/cli.js~408CLI 命令解析和执行流程
src/typescript.js~15TypeScript 编译器版本发现与加载
src/@@notfound.js1不存在模块的运行时 require 占位

Loaders (src/loaders/)

文件职责
relocate-loader.js资源重定位（代理到 @vercel/webpack-asset-relocator-loader）
ts-loader.jsTypeScript 编译（代理到 ts-loader，过滤兼容性警告）
empty-loader.js过滤不可静态分析的包（如 uglify-js）
shebang-loader.js移除 shebang 行以避免解析错误
stringify-loader.js将文件内容转为字符串导出
notfound-loader.js将未找到的模块转为运行时 require
uncacheable.js标记模块为不可缓存

工具函数 (src/utils/)

文件职责
get-package-base.js从路径中提取包根目录
has-type-module.js检测文件是否在 "type": "module" 包边界内
ncc-cache-dir.js确定缓存目录位置
shebang.jsShebang 行正则表达式

发布产物

dist/ 目录是发布到 npm 的唯一内容（由 package.json 的 "files": ["dist"] 控制）。ncc 使用自身来编译自身（自举），所以 dist/ 中的文件是 ncc 编译 src/ 产生的单文件产物。

依赖关系概览

项目的 devDependencies 包含两类：

  1. 构建依赖：webpack、terser、ts-loader、@vercel/webpack-asset-relocator-loader、source-map-support 等 — 被编译进 dist/
  2. 测试依赖：大量 npm 包（express、mongoose、pg、firebase 等）— 用于集成测试，验证 ncc 能正确打包这些常用包