可能是最全的unbuild使用文档

如果你想开发一个 npm 包或者一个小工具，你是不是或多或少的在选 webpack、rollup、vite等打包工具时而纠结过，亦或是好不容易选了一个打包工具，却又因为需要进行一堆的配置望而却步。

哈哈那你应该看看这篇文章，了解一下 unbuild 的基本使用，或许会让你的困惑瞬间消散也能提升自己的开发效率💪。

unbuild

什么是 unbuild 呢？unbuild 是一个基于 rollup 的打包工具。官方README中描述它有以下这些优势。

• 强大的构建功能 - unbuild 集成了 Rollup 构建工具，支持 TypeScript，并能生成 CommonJS 和模块格式以及类型声明，提供了丰富的构建功能。
• 自动化配置 - unbuild 可以从 package.json 文件中自动推断构建配置和入口点，减少了手动配置的工作量。
• 与 mkdist 集成，通过文件到文件的转译生成无捆绑的 dist
• 使用 jiti 开发过程中只需要一次编译之后的改动都可以实时同步调试。而无需在开发过程中监视和重建

unbuild: github.com/unjs/unbuil...

mkdist: github.com/unjs/mkdist

jiti: github.com/unjs/jiti

简单说也就是说 unbuild 替帮我们做了很多的工作，不需要在进行过多的配置就能work，只需要专注于代码逻辑即可。

但是目前对于中文区的开发者来说有一个小缺点就是文档支持的不是很好，所以这也是我写这篇文章的目的。习惯各位可以当一个文档来看。

基本使用

基本的安装步骤就不用多说了，使用你擅长或者喜欢的包管理工具进行安装即可。这里以 npm 为例：

npm install unbuild -D

此处我假设你有了一个简单的ts项目 src/index.ts。这时候需要在项目中的 package.json 中添加一行 script

export const log = (...args) => {
  console.log(...args);
};

{
  "scripts": {
    "build": "unbuild"
  }
}

然后在终端运行以下命令即可进行打包，并默认会为你生成 commonjs 和 esm 两种格式的产物。

npm run build

配置

当然默认配置不能满足所有的需求，unbuild 也支持进行自定义配置。它的配置需要创建一个 config 文件，文件的名字以固定的 build.config 开头，后缀支持很多种格式 {js,cjs,mjs,ts,mts,cts,json} 自行选择即可。

当然 unbuild 也支持在终端指定一些简单的配置，文章后面会进行简述，因为我们主要关注配置文件即可。

以下是一个配置文件的基本写法

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index.ts'],
  outDir: 'dist',
})

那除了这些还有哪些配置项呢？unbuild 的文档上写的确实很少，所以接下来我们一个个来看吧。

name

在 unbuild 中，name 配置用于指定构建生成的文件的名称。它通常用于在输出目录中为构建文件命名。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index.js'],
  outDir: 'dist',
  name: 'bundle', // 设置构建生成的文件名为 "bundle"
});

rootDir

在 unbuild 中，rootDir 配置用于指定 TypeScript 源代码文件的根目录。这个配置告诉 TypeScript 编译器在哪里可以找到项目的源代码文件。其实大部分时候我们不需要关注这个配置

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index.js'],
  outDir: 'dist',
  name: 'bundle', // 设置构建生成的文件名为 "bundle"
  rootDir: 'src',
});

entries

在 unbuild 中，entries 配置用于指定构建过程中的入口文件或入口模块。entries 可以是一个数组也可以是一个字符串，如果是数组则表示有多个入口，每一项可以指定为一个对象也可以是一个字符串

import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: [
    "./src/index",
    {
      builder: "mkdist",
      input: "./src/package/components/",
      outDir: "./build/components",
    },
  ],
});

clean

在 unbuild 中，clean 配置用于控制是否自动清空输出目录。

sourcemap

在 unbuild 中，sourcemap 配置用于控制是否生成源映射文件。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index.js'],
  outDir: 'dist',
  name: 'bundle', // 设置构建生成的文件名为 "bundle",
  sourcemap: true
});

declaration

在 unbuild 中，declaration 配置用于指定是否生成 .d.ts 文件。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index.js'],
  outDir: 'dist',
  name: 'bundle', // 设置构建生成的文件名为 "bundle"
  declaration: true
});

outDir

在 unbuild 中，outDir 配置用于指定构建输出的目录。通过这个配置，你可以定义构建过程中生成的文件的输出目录。这样可以将构建产物统一输出到指定的目录中，便于管理和部署。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  outDir: 'dist',
});

stub

在 unbuild 中，stub 配置用于指定是否开启 stub 模式。开启 stub 模式后你的构建产物里是使用的 jiti 来做链接，这样你只需要构建一次，后续所有的源码改动都可以实时得到反应。但一般只在开发中使用，所以我们只需要使用命令行命令就行

stubOptions

在 unbuild 中，stubOptions 配置用于指定一些 jiti 的配置。这里就不展开了，需要的可以自行查找 jiti 的文档，一般不需要配置

externals

在 unbuild 中，externals 配置用于指定哪些模块或库应该被视为外部依赖，不会被包含在最终的构建产物中。这个配置允许你明确地告诉构建工具哪些模块或库是外部的，需要在运行时从外部引入，而不是被打包进最终的构建结果中。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  externals: ['lodash']
});

alias

在 unbuild 中，alias 配置用于创建模块导入的别名，以便在代码中使用更简洁的路径来引用模块。这个配置允许你为模块路径指定别名，从而简化模块引入的过程。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  alias: {
    '@components': './src/components',
    '@utils': './src/utils',
    // 其他别名配置...
  }
})

replace

在 unbuild 中，replace 配置用于指定构建过程中的文本替换规则。通过这个配置，你可以定义一些替换规则，以便在构建过程中对源代码中的文本进行替换。

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  replace: {
    __DEV__: JSON.stringify(process.env.NODE_ENV === 'development'),
  },
})

比如将 __DEV__ 替换为当前环境是否为开发环境的布尔值

failOnWarn

在 unbuild 中，failOnWarn 配置用于控制是否在出现警告时终止构建过程。当 failOnWarn 设置为 true 时，任何警告都会被视为错误，导致构建过程中止。而当 failOnWarn 设置为 false 时，警告不会导致构建失败，构建过程会继续进行。

rollup

在 unbuild 中，rollup 配置用于配置 rollup 构建工具的选项。通过这个配置，你可以指定一些与 rollup 相关的参数，以下列出的都是支持的选项，这里就不对每一项展开了，需要可自行查阅 rollup 的官方文档

• emitCJS
• cjsBridge
• inlineDependencies
• output // 使用最多的一项
• replace
• alias
• resolve
• json
• esbuild
• commonjs
• dts

简单举例：使用 ubuild 打一个 umd 格式的包

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  declaration: true,
  rollup: {
    output: {
      name: 'Vue',
      format: 'umd'
    }
  }
})

preset

在 unbuild 中，preset 配置用于指定预设的构建配置。通过使用预设，你可以定义一组预先配置好的构建选项，以便在不同的项目中重复使用，从而提高开发效率并确保一致性。preset，它可以是一个对象也可以是一个函数 BuildConfig | (() => BuildConfig);

import { defineBuildConfig } from 'unbuild'
import myPreset from './myPreset'
export default defineBuildConfig({
  declaration: true,
  preset: {
    ...myPreset
  }
})

或者

import { defineBuildConfig } from 'unbuild'
import myPreset from './myPreset'
export default defineBuildConfig({
  declaration: true,
  preset: myPreset() // 需要返回的是unbuild的配置
})

hooks

在 unbuild 中，hooks 配置用于定义构建过程中的钩子函数，以便在特定的构建阶段执行自定义的操作。这个配置允许你在构建过程中插入自定义的逻辑，以满足特定的需求或执行额外的操作。以下是 unbuild 目前支持的 hook

"build:prepare": (ctx: BuildContext) => void | Promise<void>;
"build:before": (ctx: BuildContext) => void | Promise<void>;
"build:done": (ctx: BuildContext) => void | Promise<void>;
"rollup:options": (ctx: BuildContext, options: RollupOptions) => void | Promise<void>;
"rollup:build": (ctx: BuildContext, build: RollupBuild) => void | Promise<void>;
"rollup:dts:options": (ctx: BuildContext, options: RollupOptions) => void | Promise<void>;
"rollup:dts:build": (ctx: BuildContext, build: RollupBuild) => void | Promise<void>;
"rollup:done": (ctx: BuildContext) => void | Promise<void>;
"mkdist:entries": (ctx: BuildContext, entries: MkdistBuildEntry[]) => void | Promise<void>;
"mkdist:entry:options": (ctx: BuildContext, entry: MkdistBuildEntry, options: MkdistOptions) => void | Promise<void>;
"mkdist:entry:build": (ctx: BuildContext, entry: MkdistBuildEntry, output: {
    writtenFiles: string[];
}) => void | Promise<void>;
"mkdist:done": (ctx: BuildContext) => void | Promise<void>;
"untyped:entries": (ctx: BuildContext, entries: UntypedBuildEntry[]) => void | Promise<void>;
"untyped:entry:options": (ctx: BuildContext, entry: UntypedBuildEntry, options: any) => void | Promise<void>;
"untyped:entry:schema": (ctx: BuildContext, entry: UntypedBuildEntry, schema: Schema) => void | Promise<void>;
"untyped:entry:outputs": (ctx: BuildContext, entry: UntypedBuildEntry, outputs: UntypedOutputs) => void | Promise<void>;
"untyped:done": (ctx: BuildContext) => void | Promise<void>;

其中也有没列的选项，和写的不全的地方，因为笔者也没有搞清楚作用...哈哈哈

unbuild的命令行选项

我们可以通过 npx unbuild --help 来进行查看它支持的命令行选项

USAGE unbuild [OPTIONS] [DIR]

ARGUMENTS

  DIR    The directory to build

OPTIONS

       --stub    Stub build                        
     --minify    Minify build                      
  --sourcemap    Generate sourcemaps (experimental)

这里用的最多就是 --stub 和 --minify，我们可以改一下我们的 scripts，在开发时支持 stub 模式，在打包时支持 minify

{
  "scripts": {
    "build": "unbuild --minify",
    "dev": "unbuild --stub",
  }
}

如果你看到了这里那你对 unbuild 的使用基本上没什么问题，需要什么咱就配什么就行了😁

感谢您的阅读，您的点赞关注收藏就是对我最大的支持🙏🏻。

另外你也可以关注我的公众号：前端随心记。获取最新内容