---
title: "Library 打包"
locale: "zh"
version: "current"
canonicalUrl: "https://farmfe.org/zh/docs/features/library"
publicationStatus: "prerelease"
---

<a id="library-打包"></a>
# Library 打包


Farm 支持将项目构建为 **库（library）** ——即生成供其他包消费的输出，而非直接在浏览器或 Node.js 环境中运行。


将 [` output.targetEnv `](</zh/docs/config/compilation-options#output-targetenv>) 设置为 ` "library" ` 即可启用库模式：


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
  compilation: {
    input: { index: './src/index.ts' },
    output: {
      targetEnv: 'library',
      format: 'esm',
    },
  },
});
```


<a id="输出格式"></a>
## 输出格式


在库模式下，你可以通过向 [` output.format `](</zh/docs/config/compilation-options#output-format>) 传入数组，在一次构建中同时产出多种模块格式：


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
  compilation: {
    input: { index: './src/index.ts' },
    output: {
      targetEnv: 'library',
      format: ['esm', 'cjs'],
    },
  },
});
```


支持的格式：` "esm" `、` "cjs" `、` "umd" `、` "iife" `、` "system" `、` "amd" `。


<a id="打包类型"></a>
## 打包类型


Farm 编译器有三种库打包策略，见 [` output.libraryBundleType `](</zh/docs/config/compilation-options#output-librarybundletype>)：



> [!NOTE]
> 备注
> 
> V2 候选版的 JavaScript API 已支持在 ` targetEnv ` 为 ` library ` 时设置 ` compilation.output.libraryBundleType `。可选 ` single-bundle `、` multiple-bundle ` 或 ` bundle-less `；省略时保留编译器默认的 ` single-bundle `。正式 V2 发布前，请使用匹配的候选包。



<a id="single-bundle默认"></a>
### ` single-bundle `（默认）


将所有源模块合并为 **每种格式一个输出文件**。这是最简单的选项，适合小型库或希望消费者只拿到单一文件的场景。



> [!NOTE]
> 备注
> 
> ` single-bundle ` 仅支持单一入口。若配置了多个入口，Farm 会抛出错误。



<a id="multiple-bundle"></a>
### ` multiple-bundle `


每个入口产出独立的打包文件。入口之间共享的内部模块会被提取为独立的共享 chunk，类似于应用的代码分割。


<a id="bundle-less"></a>
### ` bundle-less `


每个源文件独立编译并产出为自己的输出文件，**保留原始目录结构**。这是组件库的推荐方式，消费者可以按需导入单个模块，从而享受 tree-shaking 优化。


使用 ` bundle-less ` 时，输出保留源代码结构。下方文件名仅为示意：默认输出可能包含内容哈希，可通过 ` output.filename ` 和 ` output.entryFilename ` 调整命名。


```text
src/
  index.ts
  Button.tsx
  utils/
    format.ts
```


对应产出：


```text
dist/
  index.js      (esm)
  Button.js
  utils/
    format.js
  index.cjs     (cjs)
  Button.cjs
  utils/
    format.cjs
```



> [!TIP]
> 提示
> 
> 对于大多数 UI 组件库，` bundle-less ` 是首选方案。它为每个源模块产出一个文件，让消费者可以精确地按需导入，而无需加载整个库。



<a id="外部依赖externals"></a>
## 外部依赖（Externals）


使用 [` compilation.external `](</zh/docs/config/compilation-options#externals>) 将不应打入库的依赖标记为外部依赖：


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
  compilation: {
    input: { index: './src/index.ts' },
    output: {
      targetEnv: 'library',
      format: ['esm', 'cjs'],
    },
    external: ['react', 'react-dom'],
  },
});
```


对于 ` iife ` 或 ` umd ` 格式，可通过 [` output.externalGlobals `](</zh/docs/config/compilation-options#outputexternalglobals>) 将外部模块名映射为全局变量名：


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
  compilation: {
    input: { index: './src/index.ts' },
    output: {
      targetEnv: 'library',
      format: 'umd',
      name: 'MyLibrary',
      externalGlobals: {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
    },
    external: ['react', 'react-dom'],
  },
});
```


<a id="输出文件名"></a>
## 输出文件名


通过 [` output.entryFilename `](</zh/docs/config/compilation-options#outputentryfilename>) 和 [` output.filename `](</zh/docs/config/compilation-options#outputfilename>) 自定义输出文件名。支持 ` [entryName] `、` [ext] `、` [hash] `、` [contentHash] ` 等模板占位符：


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
  compilation: {
    output: {
      targetEnv: 'library',
      format: ['esm', 'cjs'],
      entryFilename: '[entryName].[ext]',
      filename: '[resourceName].[ext]',
    },
  },
});
```