更新记录

1.0.1（2026-09-10） 下载此版本

重构设计

1.0.0（2026-09-10） 下载此版本

发布hbx-env-pack插件

平台兼容性

hbx-env-pack — HBuilderX 环境打包插件

打包前选一个环境，构建时把那个环境的 .env.* 注入 process.env。选什么打什么。

只支持 App。 H5 和小程序请用官方的自定义运行/发行（package.json → uni-app.scripts， 一个环境一个菜单项，env 由编译器直接注入）—— 那条路覆盖不到 App。

三部分组成

插件负责写「当前是哪个环境」，npm 包负责读它并注入。两个都要装，缺一个不生效。

接入四步

1. 装 npm 包

npm i -D hbx-env-pack-inject

2. 建各环境的变量文件（项目根，提交到仓库）

# .env.dev
VUE_APP_HOST=https://api-dev.example.com

# .env.prod
VUE_APP_HOST=https://api.example.com

只认 VUE_APP_ 前缀——这条是插件写死的，改不了（见下）。

3. 写 vue.config.js（项目根，必须存在）

const { withEnvInject } = require('hbx-env-pack-inject')

module.exports = withEnvInject({
  // 项目自己的 vue-cli 配置照常写在这里，跟这个包互不干扰
})

只装插件、不写这个文件，选环境不会有任何效果——包能打出来，但接口地址没变。 也别写成 module.exports = require('hbx-env-pack-inject')，那样等于把项目的配置文件整个占掉。

别改 configFile 和 prefix。 插件把 env-pack.json 和 VUE_APP_ 都写死了， 项目这边改了它俩就对不上：prefix: 'CUSTOM_' 的话，插件的校验会认为环境里 一个变量都没有，环境选不进去（单选框拨回原环境，mode 永远写不进去）。 这两个选项是给不用插件的纯 vue-cli 项目留的。

4. 代码里读

export const HOST = process.env.VUE_APP_HOST
export const BASE_URL = `${HOST}/api`

不要再写任何环境相关的字面值。

打包流程

1. 菜单栏 发行 → 环境打包（选择环境后打包）
2. 弹窗里选打包形态（app 整包 / wgt 资源包）、环境、版本号，点「写入并打包」
3. 出包前想确认打的是哪个环境：发行 → 查看当前打包环境（不打包，只报一句）

环境是「选中就生效」的：点一下环境单选框，env-pack.json 的 mode 当场就写好了。 所以取消弹窗不会回退环境——选完不用再点一次提交才知道生效没有。打包形态、版本号 这两个则只在点提交时才动（版本号尤其不能跟着单选走，否则点几下就涨几次）。

弹窗底部会把这个环境的变量一条条摊开，变量名和值都显示，切环境时跟着换：

/.env.prod
VUE_APP_HOST = https://api.example.com

选错环境在这里就能看出来，不用等打完包才发现。环境配得不对（文件不存在、或没写 file） 时，这里直接显示原因，并且不会写盘：单选框拨回原环境，宁可保持现状， 也不让 mode 指到一个读不出变量的文件上。

插件的选择是「粘性」的——选了 prod 之后，即使下次不绕插件、直接点原生「发行」菜单， 也仍然按 prod 打包。所以出包前用「查看当前打包环境」确认一下最稳妥。

配置文件 env-pack.json

放在项目根，提交到仓库。首次执行命令时若不存在会自动生成一份带默认值的，照着改即可。

{
  "mode": "dev",
  "manifestFilePath": "/manifest.json",
  "envList": [
    { "id": "dev",  "label": "开发", "file": "/.env.dev" },
    { "id": "prod", "label": "生产", "file": "/.env.prod" }
  ],
  "appPackModes": [
    { "id": "app", "label": "app 整包" },
    { "id": "wgt", "label": "wgt 资源包" }
  ],
  "versionModes": [
    { "id": "none", "label": "不修改" },
    { "id": "0", "label": "主版本 +1" },
    { "id": "1", "label": "副版本 +1" },
    { "id": "2", "label": "修订号 +1" }
  ]
}

插件只定点改写 mode 那一行，所以除了这一行不会产生别的 diff。

另有一份 .hbuilderx/env-pack.local.json，只记录上次选的打包形态，每打一次包都会变。 不想让它在 git 里产生噪音就加进 .gitignore。

新增一个环境

以加一个 test（测试）环境为例，两步：

1. 建 .env.test，照着 .env.dev 写，改掉里面的 VUE_APP_HOST
2. 在 env-pack.json 的 envList 里加一项：

{ "id": "test", "label": "测试", "file": "/.env.test" }

不用改代码。file 可以指向任意路径（不必叫 .env.<id>）。

注意事项

版本号会被改：默认选项是「不修改」，保持原样。选了某项自增的话，versionCode 的算法是 主*10000 + 副*100 + 修订（1.0.16 → 10016），保证始终递增；你的包第一次会从 1016 跳到 10016（只跳这一次），只要服务端的升级判断按「更大即更新」来就没问题。

环境变量是编译期写死的：改完环境必须重新运行/发行，热更新不会重新注入。 想确认某个包到底是哪个环境，看打包时控制台输出的这一行：

[env] 环境=prod（来源：env-pack.json）加载 /.env.prod -> VUE_APP_HOST

来源 是 env-pack.json 说明走对了；是 NODE_ENV 说明没读到 mode。

mode 会进 git：每切一次环境打包，env-pack.json 都会变一行——这是为了让新克隆的项目 自带一个确定的默认环境。多人协作时注意别把别人切的 mode 顺手带进提交。

排障

已知限制

• 只负责 App 的「打包前切环境」，不做小程序上传、不做版本发布
• 不做「按 id 推导环境文件名」：envList 每项的 file 必填
• 改版本号依赖 HBuilderX 的 hx.util.readJSONValue/writeJSONValue（manifest.json 带注释， 不能用 JSON.parse）；不启用版本号功能（选「不修改」）就完全不碰这条路径

为什么「这次用哪个环境」非得落一个文件、为什么 vue.config.js 躲不掉、 为什么包名不能叫 vue-cli-plugin-*，见 skills/uni-app-env-pack/reference.md。