@frefly/print-build-info 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,15 @@
1
1
  # @frefly/print-build-info
2
2
 
3
- 前端打包信息输出 Vite 插件。在 `vite build` 结束后,将本次构建的元信息(运行指令、分支、提交 id、打包时长、Node/V8 版本、`VITE_*` 环境变量等)写入项目根目录的 `buildInfo.txt`。
3
+ 前端打包信息输出插件。构建结束后,将本次构建的元信息(运行指令、分支、提交 id、打包时长、Node/V8 版本、环境变量等)写入项目根目录的 `buildInfo.txt`,便于排查线上问题对应的构建来源。
4
+
5
+ **特性**
6
+
7
+ - 同时支持 **Vite**(`vite.config.js`)和 **Webpack / Vue CLI**(`vue.config.js`)
8
+ - 同时提供 ESM 和 CommonJS 两种格式:
9
+ - ESM:`import { printBuildInfo } from '@frefly/print-build-info'`
10
+ - CJS:`const { WebpackPrintBuildInfo } = require('@frefly/print-build-info')`
11
+ - 仅在构建命令下生效,`vite dev` / `webpack serve` 不会触发写入
12
+ - 构建失败时不写入文件,git 信息缺失时留空不中断构建
4
13
 
5
14
  ## 安装
6
15
 
@@ -8,8 +17,12 @@
8
17
  pnpm add -D @frefly/print-build-info
9
18
  ```
10
19
 
20
+ 无需安装 peer 依赖即可使用(`vite` / `webpack` 由项目自身提供)。
21
+
11
22
  ## 使用
12
23
 
24
+ ### Vite 项目
25
+
13
26
  在 `vite.config.js` 中注册插件,并把 `loadEnv` 返回的环境变量传入:
14
27
 
15
28
  ```js
@@ -29,11 +42,39 @@ export default defineConfig(({ mode }) => {
29
42
 
30
43
  > 插件仅在 `build` 命令下生效(`apply: 'build'`),`vite dev` 不会注册其钩子。
31
44
 
45
+ ### Vue CLI 项目
46
+
47
+ 在 `vue.config.js` 中注册 Webpack 插件:
48
+
49
+ ```js
50
+ const { WebpackPrintBuildInfo } = require('@frefly/print-build-info')
51
+
52
+ module.exports = {
53
+ configureWebpack: {
54
+ plugins: [new WebpackPrintBuildInfo({ env: process.env })]
55
+ }
56
+ }
57
+ ```
58
+
59
+ 执行 `vue-cli-service build` 后,会在项目根目录生成 `buildInfo.txt`。
60
+
61
+ ### 自定义环境变量前缀
62
+
63
+ 两种插件均支持 `envPrefix` 选项,适配不同项目规范:
64
+
65
+ ```js
66
+ // Vite
67
+ printBuildInfo(env, { envPrefix: 'APP_' })
68
+
69
+ // Webpack
70
+ new WebpackPrintBuildInfo({ env: process.env, envPrefix: 'APP_' })
71
+ ```
72
+
32
73
  ## 输出示例
33
74
 
34
75
  ```
35
- 运行指令:vite build --mode sit
36
- 当前运行环境:sit
76
+ 运行指令:vite build --mode dev
77
+ 当前运行环境:dev
37
78
  当前打包分支:main
38
79
  分支最后提交id:4a4f802fb58f59bc13111f264c401012345e852d
39
80
  打包开始时间:2026/6/22 17:30:33
@@ -44,51 +85,60 @@ export default defineConfig(({ mode }) => {
44
85
  NODE_ENV:production
45
86
 
46
87
  全局变量:
47
- VITE_APP_ENV=sit
88
+ VITE_APP_ENV=dev
48
89
  VITE_APP_BASE_API=/api
49
90
  ```
50
91
 
51
92
  输出字段说明:
52
93
 
53
- | 字段 | 来源 |
54
- | -------------- | ----------------------------------------------- |
55
- | 运行指令 | `process.env.npm_lifecycle_script` |
56
- | 当前运行环境 | `env.VITE_APP_ENV` |
57
- | 当前打包分支 | `git rev-parse --abbrev-ref HEAD`(失败时为空) |
58
- | 分支最后提交id | `git rev-parse HEAD`(失败时为空) |
59
- | 打包开始时间 | `buildStart` 钩子触发时刻 |
60
- | 打包结束时间 | `buildEnd` 钩子触发时刻 |
61
- | 打包花费时长 | `buildEnd - buildStart`(秒,保留 2 位小数) |
62
- | 当前node版本 | `process.version` |
63
- | 当前v8内核版本 | `process.versions.v8` |
64
- | NODE_ENV | `process.env.NODE_ENV` |
65
- | 全局变量 | `env` 中所有以 `VITE_` 开头的键值对 |
94
+ | 字段 | 来源 |
95
+ | -------------- | ----------------------------------------------------------- |
96
+ | 运行指令 | `process.env.npm_lifecycle_script` |
97
+ | 当前运行环境 | `env[envPrefix + 'APP_ENV']`,回退 `env[envPrefix + 'ENV']` |
98
+ | 当前打包分支 | `git rev-parse --abbrev-ref HEAD`(失败时为空) |
99
+ | 分支最后提交id | `git rev-parse HEAD`(失败时为空) |
100
+ | 打包开始时间 | Vite `buildStart` / Webpack `apply` 时刻 |
101
+ | 打包结束时间 | Vite `buildEnd` / Webpack `done` 钩子触发时刻 |
102
+ | 打包花费时长 | 结束 - 开始(秒,保留 2 位小数) |
103
+ | 当前node版本 | `process.version` |
104
+ | 当前v8内核版本 | `process.versions.v8` |
105
+ | NODE_ENV | `process.env.NODE_ENV` |
106
+ | 全局变量 | `env` 中所有以 `envPrefix` 开头的键值对 |
66
107
 
67
108
  ## API
68
109
 
69
- ### `printBuildInfo(env)`
110
+ ### `printBuildInfo(env?, options?)` — Vite 插件
70
111
 
71
- | 参数 | 类型 | 必填 | 说明 |
72
- | ----- | ------------------------ | ---- | -------------------------------------------------------------------- |
73
- | `env` | `Record<string, string>` | 是 | Vite `loadEnv()` 返回的环境变量对象。只有 `VITE_` 前缀的键会被写入。 |
112
+ | 参数 | 类型 | 默认值 | 说明 |
113
+ | ------------------- | ------------------------ | ------------- | --------------------------------------- |
114
+ | `env` | `Record<string, string>` | `process.env` | 环境变量对象,推荐传 `loadEnv()` 的结果 |
115
+ | `options.envPrefix` | `string` | `'VITE_'` | 环境变量前缀,只有该前缀的键会被写入 |
74
116
 
75
- 返回值为 Vite 插件对象:
117
+ 返回 Vite 插件对象(`name` / `enforce: 'post'` / `apply: 'build'`)。
76
118
 
77
- | 属性 | 值 |
78
- | --------- | ------------------ |
79
- | `name` | `'printBuildInfo'` |
80
- | `enforce` | `'post'` |
81
- | `apply` | `'build'` |
119
+ ### `new WebpackPrintBuildInfo(options?)` — Webpack 插件
120
+
121
+ | 参数 | 类型 | 默认值 | 说明 |
122
+ | ------------------- | ------------------------ | ------------- | ------------------------------------ |
123
+ | `options.env` | `Record<string, string>` | `process.env` | 环境变量对象 |
124
+ | `options.envPrefix` | `string` | `'VUE_APP_'` | 环境变量前缀,Vue CLI 默认前缀即为此 |
82
125
 
83
126
  ## 输出位置
84
127
 
85
- `buildInfo.txt` 写入 Vite 的 `config.root`(即调用方项目根目录)。不依赖 `process.cwd()`,因此在 monorepo / 通过 `--config` 指定外部配置文件等场景下也能写到正确位置。
128
+ `buildInfo.txt` 写入 Vite 的 `config.root` / Webpack 的 `compiler.context`(即调用方项目根目录)。不依赖 `process.cwd()`,因此在 monorepo、通过 `--config` 指定外部配置文件等场景下也能写到正确位置。
86
129
 
87
130
  ## 注意事项
88
131
 
89
132
  - 非 git 仓库或未安装 git 时,分支与提交 id 字段会留空,不会中断构建。
90
- - `buildEnd` 在同一次构建中可能被多次触发,插件内部做了幂等保护,文件只会写一次。
91
- - 构建失败时(`buildEnd(err)` 收到 error)不会写入文件。
133
+ - Vite 的 `buildEnd` 在同一次构建中可能被多次触发,插件内部做了幂等保护,文件只会写一次。
134
+ - 构建失败时(Vite `buildEnd(err)` / Webpack `stats.hasErrors()`)不会写入文件。
135
+ - 建议将 `buildInfo.txt` 加入 `.gitignore`,避免构建产物提交到仓库。
136
+
137
+ ## 开发
138
+
139
+ ```bash
140
+ pnpm build # 构建产物到 dist/(ESM: dist/index.js, CJS: dist/index.cjs)
141
+ ```
92
142
 
93
143
  ## 许可证
94
144
 
package/dist/index.cjs ADDED
@@ -0,0 +1,112 @@
1
+ 'use strict';
2
+
3
+ var node_child_process = require('node:child_process');
4
+ var fs = require('node:fs');
5
+ var path = require('node:path');
6
+
7
+ /**
8
+ * 执行 git 命令并返回 trim 后的输出;命令失败时返回空字符串
9
+ * @param {string} cmd
10
+ * @returns {string}
11
+ */
12
+ const safeGit = cmd => {
13
+ try {
14
+ return node_child_process.execSync(cmd, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
15
+ } catch {
16
+ return ''
17
+ }
18
+ };
19
+
20
+ /**
21
+ * 收集打包信息并写入项目根目录下的 buildInfo.txt
22
+ * @param {object} options
23
+ * @param {Record<string, string|undefined>} options.env 环境变量对象
24
+ * @param {string} options.envPrefix 环境变量前缀,如 'VITE_' 或 'VUE_APP_'
25
+ * @param {number} options.startTime 构建开始时间戳
26
+ * @param {string} options.projectRoot 项目根目录
27
+ */
28
+ const writeBuildInfo = ({ env, envPrefix, startTime, projectRoot }) => {
29
+ const endTime = Date.now();
30
+ const lines = [
31
+ `运行指令:${process.env.npm_lifecycle_script ?? ''}`,
32
+ // 兼容两种命名惯例:Vite 的 VITE_APP_ENV 与 Vue CLI 的 VUE_APP_ENV
33
+ `当前运行环境:${env[`${envPrefix}APP_ENV`] ?? env[`${envPrefix}ENV`] ?? ''}`,
34
+ `当前打包分支:${safeGit('git rev-parse --abbrev-ref HEAD')}`,
35
+ `分支最后提交id:${safeGit('git rev-parse HEAD')}`,
36
+ `打包开始时间:${new Date(startTime).toLocaleString()}`,
37
+ `打包结束时间:${new Date(endTime).toLocaleString()}`,
38
+ `打包花费时长:${((endTime - startTime) / 1000).toFixed(2)}s`,
39
+ `当前node版本:${process.version}`,
40
+ `当前v8内核版本:${process.versions.v8}`,
41
+ `NODE_ENV:${process.env.NODE_ENV ?? ''}`,
42
+ '',
43
+ '全局变量:'
44
+ ];
45
+
46
+ for (const key of Object.keys(env)) {
47
+ if (key.startsWith(envPrefix)) {
48
+ lines.push(`${key}=${env[key]}`);
49
+ }
50
+ }
51
+
52
+ const outputPath = path.resolve(projectRoot, 'buildInfo.txt');
53
+ fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
54
+ };
55
+
56
+ /**
57
+ * Vite 插件:在构建结束时将打包信息写入项目根目录下的 buildInfo.txt
58
+ * @param {Record<string, string|undefined>} [env] Vite loadEnv 返回的环境变量对象,默认 process.env
59
+ * @param {object} [options] 可选配置
60
+ * @param {string} [options.envPrefix='VITE_'] 环境变量前缀
61
+ * @returns {import('vite').Plugin}
62
+ */
63
+ function printBuildInfo(env = process.env, { envPrefix = 'VITE_' } = {}) {
64
+ let projectRoot = process.cwd();
65
+ let startTime = 0;
66
+ let written = false;
67
+
68
+ return {
69
+ name: 'printBuildInfo',
70
+ enforce: 'post',
71
+ apply: 'build',
72
+ configResolved(config) {
73
+ projectRoot = config.root || process.cwd();
74
+ },
75
+ buildStart() {
76
+ startTime = Date.now();
77
+ },
78
+ buildEnd(err) {
79
+ if (err || written) return
80
+ written = true;
81
+
82
+ writeBuildInfo({ env, envPrefix, startTime, projectRoot });
83
+ }
84
+ }
85
+ }
86
+
87
+ /**
88
+ * Webpack 插件:供 vue.config.js 使用,构建完成后将打包信息写入项目根目录下的 buildInfo.txt
89
+ * @param {object} [options]
90
+ * @param {Record<string, string|undefined>} [options.env] 环境变量对象,默认 process.env
91
+ * @param {string} [options.envPrefix='VUE_APP_'] 环境变量前缀
92
+ */
93
+ class WebpackPrintBuildInfo {
94
+ constructor({ env = process.env, envPrefix = 'VUE_APP_' } = {}) {
95
+ this.env = env;
96
+ this.envPrefix = envPrefix;
97
+ }
98
+
99
+ apply(compiler) {
100
+ const { env, envPrefix } = this;
101
+ const startTime = Date.now();
102
+ const projectRoot = compiler.context;
103
+
104
+ compiler.hooks.done.tap('printBuildInfo', stats => {
105
+ if (stats.hasErrors()) return
106
+ writeBuildInfo({ env, envPrefix, startTime, projectRoot });
107
+ });
108
+ }
109
+ }
110
+
111
+ exports.WebpackPrintBuildInfo = WebpackPrintBuildInfo;
112
+ exports.printBuildInfo = printBuildInfo;
package/dist/index.js ADDED
@@ -0,0 +1,109 @@
1
+ import { execSync } from 'node:child_process';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+
5
+ /**
6
+ * 执行 git 命令并返回 trim 后的输出;命令失败时返回空字符串
7
+ * @param {string} cmd
8
+ * @returns {string}
9
+ */
10
+ const safeGit = cmd => {
11
+ try {
12
+ return execSync(cmd, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
13
+ } catch {
14
+ return ''
15
+ }
16
+ };
17
+
18
+ /**
19
+ * 收集打包信息并写入项目根目录下的 buildInfo.txt
20
+ * @param {object} options
21
+ * @param {Record<string, string|undefined>} options.env 环境变量对象
22
+ * @param {string} options.envPrefix 环境变量前缀,如 'VITE_' 或 'VUE_APP_'
23
+ * @param {number} options.startTime 构建开始时间戳
24
+ * @param {string} options.projectRoot 项目根目录
25
+ */
26
+ const writeBuildInfo = ({ env, envPrefix, startTime, projectRoot }) => {
27
+ const endTime = Date.now();
28
+ const lines = [
29
+ `运行指令:${process.env.npm_lifecycle_script ?? ''}`,
30
+ // 兼容两种命名惯例:Vite 的 VITE_APP_ENV 与 Vue CLI 的 VUE_APP_ENV
31
+ `当前运行环境:${env[`${envPrefix}APP_ENV`] ?? env[`${envPrefix}ENV`] ?? ''}`,
32
+ `当前打包分支:${safeGit('git rev-parse --abbrev-ref HEAD')}`,
33
+ `分支最后提交id:${safeGit('git rev-parse HEAD')}`,
34
+ `打包开始时间:${new Date(startTime).toLocaleString()}`,
35
+ `打包结束时间:${new Date(endTime).toLocaleString()}`,
36
+ `打包花费时长:${((endTime - startTime) / 1000).toFixed(2)}s`,
37
+ `当前node版本:${process.version}`,
38
+ `当前v8内核版本:${process.versions.v8}`,
39
+ `NODE_ENV:${process.env.NODE_ENV ?? ''}`,
40
+ '',
41
+ '全局变量:'
42
+ ];
43
+
44
+ for (const key of Object.keys(env)) {
45
+ if (key.startsWith(envPrefix)) {
46
+ lines.push(`${key}=${env[key]}`);
47
+ }
48
+ }
49
+
50
+ const outputPath = path.resolve(projectRoot, 'buildInfo.txt');
51
+ fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
52
+ };
53
+
54
+ /**
55
+ * Vite 插件:在构建结束时将打包信息写入项目根目录下的 buildInfo.txt
56
+ * @param {Record<string, string|undefined>} [env] Vite loadEnv 返回的环境变量对象,默认 process.env
57
+ * @param {object} [options] 可选配置
58
+ * @param {string} [options.envPrefix='VITE_'] 环境变量前缀
59
+ * @returns {import('vite').Plugin}
60
+ */
61
+ function printBuildInfo(env = process.env, { envPrefix = 'VITE_' } = {}) {
62
+ let projectRoot = process.cwd();
63
+ let startTime = 0;
64
+ let written = false;
65
+
66
+ return {
67
+ name: 'printBuildInfo',
68
+ enforce: 'post',
69
+ apply: 'build',
70
+ configResolved(config) {
71
+ projectRoot = config.root || process.cwd();
72
+ },
73
+ buildStart() {
74
+ startTime = Date.now();
75
+ },
76
+ buildEnd(err) {
77
+ if (err || written) return
78
+ written = true;
79
+
80
+ writeBuildInfo({ env, envPrefix, startTime, projectRoot });
81
+ }
82
+ }
83
+ }
84
+
85
+ /**
86
+ * Webpack 插件:供 vue.config.js 使用,构建完成后将打包信息写入项目根目录下的 buildInfo.txt
87
+ * @param {object} [options]
88
+ * @param {Record<string, string|undefined>} [options.env] 环境变量对象,默认 process.env
89
+ * @param {string} [options.envPrefix='VUE_APP_'] 环境变量前缀
90
+ */
91
+ class WebpackPrintBuildInfo {
92
+ constructor({ env = process.env, envPrefix = 'VUE_APP_' } = {}) {
93
+ this.env = env;
94
+ this.envPrefix = envPrefix;
95
+ }
96
+
97
+ apply(compiler) {
98
+ const { env, envPrefix } = this;
99
+ const startTime = Date.now();
100
+ const projectRoot = compiler.context;
101
+
102
+ compiler.hooks.done.tap('printBuildInfo', stats => {
103
+ if (stats.hasErrors()) return
104
+ writeBuildInfo({ env, envPrefix, startTime, projectRoot });
105
+ });
106
+ }
107
+ }
108
+
109
+ export { WebpackPrintBuildInfo, printBuildInfo };
package/index.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ export interface BuildInfoOptions {
2
+ /** 环境变量对象,默认 process.env */
3
+ env?: Record<string, string | undefined>
4
+ /** 环境变量前缀,Vite 插件默认 'VITE_',Webpack 插件默认 'VUE_APP_' */
5
+ envPrefix?: string
6
+ }
7
+
8
+ /**
9
+ * Vite 插件:构建结束时将打包信息写入项目根目录下的 buildInfo.txt
10
+ * @param env - Vite loadEnv 返回的环境变量对象,默认 process.env
11
+ * @param options - 可选配置
12
+ * @returns Vite 插件对象
13
+ */
14
+ export declare function printBuildInfo(
15
+ env?: Record<string, string | undefined>,
16
+ options?: { envPrefix?: string }
17
+ ): {
18
+ name: string
19
+ enforce: 'post'
20
+ apply: 'build'
21
+ }
22
+
23
+ /**
24
+ * Webpack 插件:供 vue.config.js 使用,构建完成后将打包信息写入项目根目录下的 buildInfo.txt
25
+ */
26
+ export declare class WebpackPrintBuildInfo {
27
+ constructor(options?: BuildInfoOptions)
28
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@frefly/print-build-info",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "前端打包信息输出配置",
5
5
  "keywords": [
6
6
  "print",
@@ -8,19 +8,39 @@
8
8
  "env"
9
9
  ],
10
10
  "type": "module",
11
- "main": "index.js",
11
+ "main": "./dist/index.cjs",
12
+ "module": "./dist/index.js",
13
+ "types": "./index.d.ts",
12
14
  "exports": {
13
- ".": "./index.js"
15
+ ".": {
16
+ "types": "./index.d.ts",
17
+ "import": "./dist/index.js",
18
+ "require": "./dist/index.cjs"
19
+ },
20
+ "./package.json": "./package.json"
14
21
  },
15
22
  "publishConfig": {
16
23
  "access": "public"
17
24
  },
25
+ "sideEffects": false,
18
26
  "files": [
19
- "index.js",
27
+ "dist",
28
+ "index.d.ts",
20
29
  "README.md"
21
30
  ],
31
+ "devDependencies": {
32
+ "rollup": "4.68.2"
33
+ },
34
+ "peerDependencies": {
35
+ "vite": ">=2.0.0",
36
+ "webpack": ">=5.0.0"
37
+ },
22
38
  "license": "MIT",
39
+ "engines": {
40
+ "node": ">=18"
41
+ },
23
42
  "scripts": {
24
- "release": "pnpm publish --no-git-checks"
43
+ "build": "rollup -c",
44
+ "release": "pnpm build && pnpm publish"
25
45
  }
26
46
  }
package/index.js DELETED
@@ -1,68 +0,0 @@
1
- import { execSync } from 'node:child_process'
2
- import fs from 'node:fs'
3
- import path from 'node:path'
4
-
5
- /**
6
- * 执行 git 命令并返回 trim 后的输出;命令失败时返回空字符串
7
- * @param {string} cmd
8
- * @returns {string}
9
- */
10
- const safeGit = cmd => {
11
- try {
12
- return execSync(cmd, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
13
- } catch {
14
- return ''
15
- }
16
- }
17
-
18
- /**
19
- * Vite 插件:在构建结束时将打包信息写入项目根目录下的 buildInfo.txt
20
- * @param {Record<string, string>} env Vite loadEnv 返回的环境变量对象
21
- * @returns {import('vite').Plugin}
22
- */
23
- export const printBuildInfo = env => {
24
- let projectRoot = process.cwd()
25
- let startTime = 0
26
- let written = false
27
-
28
- return {
29
- name: 'printBuildInfo',
30
- enforce: 'post',
31
- apply: 'build',
32
- configResolved(config) {
33
- projectRoot = config.root || process.cwd()
34
- },
35
- buildStart() {
36
- startTime = Date.now()
37
- },
38
- buildEnd(err) {
39
- if (err || written) return
40
- written = true
41
-
42
- const endTime = Date.now()
43
- const lines = [
44
- `运行指令:${process.env.npm_lifecycle_script ?? ''}`,
45
- `当前运行环境:${env.VITE_APP_ENV ?? ''}`,
46
- `当前打包分支:${safeGit('git rev-parse --abbrev-ref HEAD')}`,
47
- `分支最后提交id:${safeGit('git rev-parse HEAD')}`,
48
- `打包开始时间:${new Date(startTime).toLocaleString()}`,
49
- `打包结束时间:${new Date(endTime).toLocaleString()}`,
50
- `打包花费时长:${((endTime - startTime) / 1000).toFixed(2)}s`,
51
- `当前node版本:${process.version}`,
52
- `当前v8内核版本:${process.versions.v8}`,
53
- `NODE_ENV:${process.env.NODE_ENV ?? ''}`,
54
- '',
55
- '全局变量:'
56
- ]
57
-
58
- for (const key of Object.keys(env)) {
59
- if (key.startsWith('VITE_')) {
60
- lines.push(`${key}=${env[key]}`)
61
- }
62
- }
63
-
64
- const outputPath = path.resolve(projectRoot, 'buildInfo.txt')
65
- fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8')
66
- }
67
- }
68
- }