README.zh-CN.md

English | 简体中文

• 功能
• 安装
• 选项
• 用法
  • 基础用法
  • 高级用法
  • 趣味用法
  • 添加不同的 Banner
  • 可选参数格式
• License

功能

为每个 chunk 文件头部添加 banner 注释。

安装

从 npm (或者 yarn 或者 pnpm) 安装：

npm install --save-dev vite-plugin-banner

选项

插件选项类型	作用描述	使用例子
string	横幅注释的内容	基础用法
ContentCallback	请参阅下方的类型声明	添加不同的 Banner
BannerPluginOptions	请参阅下方的类型声明	可选参数格式

· Type Declarations:

/**
 * 来自 `vite.config.[ts|js]` 的一些选项
 *
 * @since 0.2.0
 */
export interface BannerPluginOptions {
  /**
   * Banner 的注释内容
   *
   * @since 从 ^0.6.0 开始支持 `ContentCallback` 类型
   */
  content: string | ContentCallback

  /**
   * Vite.js 配置的输出目录
   *
   * @see https://cn.vitejs.dev/config/build-options#build-outdir
   *
   * @default viteConfig.build.outDir
   */
  outDir?: string

  /**
   * 是否将错误信息打印到控制台
   *
   * @since 0.4.0
   *
   * @default false
   */
  debug?: boolean

  /**
   * 默认会验证内容的合法性，设置为 `false` 则不验证
   *
   * @see https://github.com/chengpeiquan/vite-plugin-banner/issues/13
   *
   * @since 0.5.0
   *
   * @default true
   */
  verify?: boolean
}

/**
 * 回调函数获取要注入的内容（或不注入）
 *
 * @since 0.6.0
 *
 * @param fileName - 当前正在处理的文件名称
 *
 * @returns
 *  1. 返回有效字符串时，返回值将成为 Banner 的内容
 *  2. 返回 Falsy 值将跳过处理（例如 `''`、`null`、`undefined` ）
 *
 * @example
 *
 * ```ts
 *  content: (fileName: string) => {
 *    // 或者使用 `switch` 语句
 *    return fileName.endsWith('.js')
 *      ? 'This message will inject into `js` files.'
 *      : 'This message will inject into other files.'
 *  }
 * ```
 */
export type ContentCallback = (fileName: string) => string | null | undefined

用法

在大多数情况下，只需使用 string 格式作为插件选项。

基础用法

在 vite.config.ts 添加：

// vite.config.ts
import banner from 'vite-plugin-banner'
// 其他依赖...

export default defineConfig({
  plugins: [banner('This is the banner content.')],
})

当你在你的项目上运行 npm run build 打包的时候，在 dist 文件夹（或者你在 vite.config.ts 配置的其他 build.outDir ），除了 vendor 文件外，所有的 js 和 css 文件都会添加一个 banner 注释在文件顶部。

例如，在生成的 app.b3a7772e.js 里:

/* This is the banner content. */
var e=Object.assign;import{M as t,d as a,u as r,c......

高级用法

当然，最理想的 banner 注释是和你的项目信息相关联。

首先，你需要更新你的 package.json 文件，像这样，包含类似的字段内容：

{
  "name": "chengpeiquan.com",
  "version": "0.1.0",
  "description": "My personal website, technology stack based on Vue.js 3.0, and Vite 2.0, use Server Side Generation.",
  "author": "chengpeiquan",
  "homepage": "https://chengpeiquan.com/"
}

然后，在你的 vite.config.ts 导入 package.json，像这样更新 banner 插件的内容：

// vite.config.ts
import pkg from './package.json'
// 其他依赖...

export default defineConfig({
  plugins: [
    banner(
      `/**\n * name: ${pkg.name}\n * version: v${pkg.version}\n * description: ${pkg.description}\n * author: ${pkg.author}\n * homepage: ${pkg.homepage}\n */`,
    ),
  ],
})

运行 npm run build 打包, 你可以看到生成出来的 banner 注释更详细：

例如，在生成的 app.6936be52.js 里:

/**
 * name: chengpeiquan.com
 * version: v0.1.0
 * description: My personal website, technology stack based on Vue.js 3.0, and Vite 2.0, use Server Side Generation.
 * author: chengpeiquan
 * homepage: https://chengpeiquan.com/
 */
var e=Object.assign;import{M as t,d as a,u as r,c......

趣味用法

如果你想制作一些个性化的 banner 注释，像什么表白啊、佛系啊、招聘信息啊什么的，可以通过一些在线生成器去制作有趣的内容。

比如在这些网站上可以直接生成:

• http://www.network-science.de/ascii/

• https://www.bootschool.net/ascii

// vite.config.ts
export default defineConfig({
  plugins: [
    banner(`
    ██   ██         ███████   ██      ██ ████████   ██    ██   ███████   ██     ██
    ░██  ░██        ██░░░░░██ ░██     ░██░██░░░░░   ░░██  ██   ██░░░░░██ ░██    ░██
    ░██  ░██       ██     ░░██░██     ░██░██         ░░████   ██     ░░██░██    ░██
    ░██  ░██      ░██      ░██░░██    ██ ░███████     ░░██   ░██      ░██░██    ░██
    ░██  ░██      ░██      ░██ ░░██  ██  ░██░░░░       ░██   ░██      ░██░██    ░██
    ░██  ░██      ░░██     ██   ░░████   ░██           ░██   ░░██     ██ ░██    ░██
    ░██  ░████████ ░░███████     ░░██    ░████████     ░██    ░░███████  ░░███████ 
    ░░   ░░░░░░░░   ░░░░░░░       ░░     ░░░░░░░░      ░░      ░░░░░░░    ░░░░░░░  
    `),
  ],
})

执行 npm run build 打包, 还是在 app.d9a287b8.js ，现在变成了：

/*
    ██   ██         ███████   ██      ██ ████████   ██    ██   ███████   ██     ██
    ░██  ░██        ██░░░░░██ ░██     ░██░██░░░░░   ░░██  ██   ██░░░░░██ ░██    ░██
    ░██  ░██       ██     ░░██░██     ░██░██         ░░████   ██     ░░██░██    ░██
    ░██  ░██      ░██      ░██░░██    ██ ░███████     ░░██   ░██      ░██░██    ░██
    ░██  ░██      ░██      ░██ ░░██  ██  ░██░░░░       ░██   ░██      ░██░██    ░██
    ░██  ░██      ░░██     ██   ░░████   ░██           ░██   ░░██     ██ ░██    ░██
    ░██  ░████████ ░░███████     ░░██    ░████████     ░██    ░░███████  ░░███████
    ░░   ░░░░░░░░   ░░░░░░░       ░░     ░░░░░░░░      ░░      ░░░░░░░    ░░░░░░░
     */
var e=Object.assign;import{M as t,d as a,u as r,c......

添加不同的 Banner

从 0.6.0 开始支持传入函数回调设置 Banner 的内容，当使用 ContentCallback 类型时，本插件会根据该函数的内部逻辑判断应该添加什么内容。

1. 返回有效字符串时，返回值将成为 Banner 的内容
2. 返回 Falsy 值将跳过处理（例如 ''、null、undefined ）

以判断文件扩展名添加两个不同的 Banner 内容为例：

e.g.

// vite.config.ts
import banner from 'vite-plugin-banner'
// 其他依赖...

export default defineConfig({
  plugins: [
    banner((fileName: string) => {
      // 或者使用 `switch` 语句
      return fileName.endsWith('.js')
        ? 'This message will inject into `js` files.'
        : 'This message will inject into other files.'
    }),
  ],
})

可选参数格式

有时候插件无法成功获取到 outDir （例如在 VitePress 里，插件通过 viteConfig.build.outDir 拿到的永远是一个 .temp 的临时目录，不是最终的输出目录），所以需要手动指定输出目录来告知插件。

以 VitePress 举例：

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'
import banner from 'vite-plugin-banner'
import pkg from '../../package.json'

const outDir = '../dist'

export default defineConfig({
  // 指定打包的输出目录
  outDir,

  // 使用 Vite 插件
  vite: {
    plugins: [
      // 请记住在这里使用 Object 格式的选项
      banner({
        outDir,
        content: `/**\n * name: ${pkg.name}\n * version: v${pkg.version}\n * description: ${pkg.description}\n * author: ${pkg.author}\n * homepage: ${pkg.homepage}\n */`,
      }),
    ],
  },
  // ...
})

除了 outDir ，还可以使用 debug 、 verify 等选项，详见上方的 选项 说明。

License

MIT License © 2021 chengpeiquan