vite-plugin-banner

English | 简体中文

功能

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

安装

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

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

选项

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

· Type Declarations:

``ts
/**
* 来自 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 格式作为插件选项。

$3

在 vite.config.ts 添加：

`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 里:

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

$3

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

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

`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 插件的内容：

`ts
// 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 里:

`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......
`

$3

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

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

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

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

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

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

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

$3

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

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

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

e.g.

`ts
// 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.'
}),
],
})
`

$3

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

以 VitePress 举例：

`ts
// 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