ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Umi 环境变量完全指南:从 .env 注入到浏览器端 define 的实战手册

Umi 环境变量完全指南:从 .env 注入到浏览器端 define 的实战手册 Umi 环境变量完全指南从 .env 注入到浏览器端 define 的实战手册【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi本指南以 Umi 官方文档 环境变量 为核心骨架系统讲解 UmiReact 社区企业级前端框架中环境变量的三种设置方式、浏览器端注入机制以及 APP_ROOT、UMI_ENV、PORT、UMI_PLUGINS 等全部内置环境变量的含义与使用场景。读完本文你将掌握如何为umi dev/umi build精确配置端口、HMR、压缩、bundle 分析等运行参数并能结合源码理解 Umi 加载.env与配置文件的实际机制从容应对跨平台、多环境、浏览器侧取值等典型工程问题。什么是 Umi 环境变量Umi 通过环境变量来完成一些特殊的配置和功能。它们与配置文件.umirc.ts/config.ts互补配置文件描述项目怎么构建而环境变量则描述本次运行用什么参数、加载什么额外能力。例如你可以不改动任何配置文件仅通过一条命令改变 dev server 的端口或者临时关闭 Babel 缓存。需要强调的是绝大多数环境变量默认只在 Umi 配置文件的 Node.js 环境内生效process.env并不会自动暴露给浏览器端代码只有少量约定前缀变量会被默认注入到浏览器中见下文在浏览器中使用环境变量。如何设置环境变量执行命令时设置最直接的注入方式是在命令前临时赋值例如改变umi dev开发服务器的端口# OS X, Linux $ PORT3000 umi dev # Windows (cmd.exe) $ set PORT3000umi dev如果需要同时在不同的操作系统中使用环境变量推荐使用工具 cross-env 来抹平平台差异$ pnpm install cross-env -D $ cross-env PORT3000 umi dev这种方式的优点是一次性、局部生效适合临时调试缺点是无法在团队内共享也不便写入 package.json 的 scripts 中跨平台复用。设置在 .env 文件中如果你的环境变量需要在开发者之间共享推荐设置在项目根目录的.env文件中例如# file .env PORT3000 BABEL_CACHEnone然后执行$ umi devumi会以 3000 端口启动 dev server并且禁用 Babel 的缓存。如果你有部分环境变量的配置在本地要做特殊配置可以配置在.env.local文件中去覆盖.env的配置。比如在之前.env的基础上你想本地开发覆盖 3000 端口而使用 4000 端口可以做如下定义# file .env.local PORT4000此时umi会以 4000 端口启动 dev server同时保持禁用 Babel 的缓存。此外.env文件中还支持以变量拼接的方式来配置环境变量例如# file .env.local FOOfoo BARbar CONCAT$FOO$BAR # CONCATfoobar从源码看加载机制Umi 在 Service 初始化阶段packages/core/src/service/service.ts调用loadEnv({ cwd, envFile: .env })其实现位于 packages/core/src/service/env.ts按顺序尝试读取项目根目录的.env与.env.local先解析dotenv的parse再做变量展开dotenv-expand的expand所以$FOO$BAR这类引用可以生效最后把结果写入process.env。.env.local后加载因此同名键会覆盖.env中的值——这正是本地覆盖共享配置的实现原理。注意事项Umi不支持.env.development/.env.production这类按环境区分的 env 文件。如需在不同的环境下有不同的变量值请使用cross-env在不同的启动命令上区分或定义在各个UMI_ENV对应的 Umi 配置文件内详见下文UMI_ENV。不建议将.env.local加入版本管理中它天然是个人本地配置应被.gitignore排除。在浏览器中使用环境变量所有通过.env环境变量文件或命令行注入的环境变量默认只在 Umi 配置文件Node.js 环境内生效在浏览器中无法直接通过process.env.VAR_NAME方式使用。如果需要暴露给浏览器端代码需通过进一步配置define来注入# .env MY_TOKENxxxxx// .umirc.ts define: { process.env.MY_TOKEN: process.env.MY_TOKEN }源码佐证在 packages/bundler-webpack/src/config/definePlugin.ts 的resolveDefine中userConfig.define的每个键都会被JSON.stringify后注入 webpack 的DefinePlugin从而让process.env.MY_TOKEN在浏览器 bundle 中被替换为具体字符串值。约定前缀 UMI_APP_Umi 约定所有以UMI_APP_开头的环境变量会默认注入到浏览器中无需配置define手动注入。同样见 definePlugin.tsprefixRE /^UMI_APP_/配合NODE_ENV、HMR、SOCKET_SERVER、ERROR_OVERLAY等固定白名单这些变量会被透传到浏览器环境。因此你可以在.env中写UMI_APP_API_HOST...然后在组件里直接process.env.UMI_APP_API_HOST。环境变量列表以下变量按字母顺序排列均为 Umi 内置识别、可直接使用的环境变量。APP_ROOT指定项目根目录。适用于 monorepo 等场景下从子目录启动、但希望 Umi 把某个上层/其他目录视为项目根的情况。注意APP_ROOT不能配在.env中只能在命令行里添加因为.env本身依赖项目根目录解析存在先有鸡还是先有蛋的问题。从源码看packages/preset-umi/src/features/monorepo/redirect.ts 中会判断process.env.APP_ROOT当设置了APP_ROOT时以当前process.cwd()作为项目根否则使用api.cwd这也是 Umi 在 monorepo 场景下重定向配置的依据之一。ANALYZE用于分析 bundle 构成默认关闭。构建后会在浏览器中打开可视化分析报告$ ANALYZE1 umi dev # 或者 $ ANALYZE1 umi build可以通过ANALYZE_PORT环境变量自定义分析报告的服务端口或通过配置项analyze自定义分析选项。BABEL_POLYFILL默认会根据targets配置为目标浏览器打全量补丁设置为none可禁用内置的补丁方案。源码中 packages/preset-umi/src/features/polyfill/polyfill.ts 通过process.env.BABEL_POLYFILL ! none来决定是否注入 polyfill。COMPRESS默认压缩 CSS 和 JS值为none时不压缩仅在build时有效。对应实现可见 packages/preset-umi/src/features/esbuildHelperChecker/esbuildHelperChecker.ts其中process.env.COMPRESS none会跳过相关的压缩产物检查。DID_YOU_KNOW设置为none会禁用「你知道吗」提示。在 packages/preset-umi/src/index.ts 中通过process.env.DID_YOU_KNOW ! none控制该提示的启用。ERROR_OVERLAY设置为none会禁用「Error Overlay」在调试 Error Boundary 时会有用。该变量同时会被透传到浏览器端见 definePlugin.ts 的ENV_SHOULD_PASS白名单。FS_LOGGER默认会开启保存物理日志值为none时不保存。同时针对 webcontainer 场景比如 StackBlitz暂不保存——见 packages/utils/src/logger.ts 中process.env.FS_LOGGER ! none !process.versions.webcontainer的判断。HMR默认开启 HMR热模块替换功能值为none时关闭。例如 packages/preset-umi/src/features/hmrGuardian/hmrGuardian.ts 会在process.env.HMR none时跳过 HMR 守护逻辑。HOST指定 dev server 监听的主机地址默认是0.0.0.0。在 packages/preset-umi/src/commands/dev/dev.ts 中process.env.HOST || DEFAULT_HOST决定了服务监听地址当 HOST 为局域网 IP 等非本机地址时SOCKET_SERVER会自动推导出对应的 HMR socket 地址见 definePlugin.ts。PORT指定端口号默认是8000。见 dev.ts 中parseInt(String(process.env.PORT || DEFAULT_PORT), 10)。当端口被占用时Umi 会默认尝试寻找下一个可用端口。SOCKET_SERVER指定用于 HMR 的 socket 服务器地址。比如$ SOCKET_SERVERhttp://localhost:8000/ umi dev从源码看SOCKET_SERVER属于ENV_SHOULD_PASS白名单会被透传到浏览器当未显式设置时若HOST为0.0.0.0/127.0.0.1/localhost之外的地址Umi 会自动拼接协议://host:port作为 socket serverdefinePlugin.ts。STRICT_PORT如果设置当端口被占用时会提示用户使用其他端口并退出进程$ STRICT_PORT8000 umi devdev.ts 中检测到process.env.STRICT_PORT后会先检查端口占用情况并打印提示端口被占用时直接退出而非自动切换。SPEED_MEASURE分析 Webpack 编译时间支持CONSOLE和JSON两种格式默认是CONSOLE$ SPEED_MEASUREJSON umi dev适合在构建性能优化时定位编译耗时瓶颈。UMI_ENV当指定UMI_ENV时会额外加载指定值的配置文件配置文件的加载优先级为config.tsconfig.${UMI_ENV}.tsconfig.${dev | prod | test}.tsconfig.${dev | prod | test}.${UMI_ENV}.tsconfig.local.ts若不指定UMI_ENV则只会加载当前环境对应的配置文件。越向下的越具体、优先级越高高优的配置可以往下移动即更具体的文件覆盖更通用的文件。注根据当前环境的不同dev、prod、test配置文件会自动加载不能将UMI_ENV的值设定成它们。从源码看优先级实现packages/core/src/config/config.ts 的getConfigFiles方法会按mainConfigFile→config.${specifiedEnv}→config.${env}→config.${env}.${specifiedEnv}→开发环境下config.local的顺序收集文件随后在getUserConfig中逐个require并以lodash.merge合并——后面的文件覆盖前面文件的同名配置这与文档中的优先级描述完全对应。specifiedEnv即来自process.env.UMI_ENV见 packages/core/src/service/service.ts 中process.env[${prefix}_ENV.toUpperCase()]的读取。UMI_PLUGINS指定umi命令执行时额外加载的插件路径多个路径使用,隔开$ UMI_PLUGINS./path/to/plugin1,./path/to/plugin2 umi devUMI_PRESETS指定umi命令执行时额外加载插件集preset的路径多个路径使用,隔开$ UMI_PRESETS./path/to/preset1,./path/to/preset2 umi devUMI_PLUGINS与UMI_PRESETS的解析统一发生在 packages/core/src/service/plugin.ts 中通过process.env[${opts.prefix}_${types}.toUpperCase()]即UMI_PLUGINS/UMI_PRESETS读取并按,拆分从而在不改动配置的情况下临时注入插件能力非常适合本地调试插件或按需启用实验性 preset。UMI_DEV_SERVER_COMPRESS默认 Umi 开发服务器自带 compress 压缩中间件这会使开发时 SSE 数据的传输无法流式获取。通过指定UMI_DEV_SERVER_COMPRESSnone来关闭 compress 压缩功能UMI_DEV_SERVER_COMPRESSnone umi dev该变量适用于开发阶段依赖 SSE如流式日志、AI 流式回复等的场景关闭压缩后数据可以实时流式到达前端。WEBPACK_FS_CACHE_DEBUG开启 webpack 物理缓存文件系统缓存的 debug 日志$ WEBPACK_FS_CACHE_DEBUG1 umi dev适合排查缓存命中/失效问题时使用帮助确认缓存是否按预期复用。实战场景速查场景推荐做法临时改 dev 端口PORT3000 umi dev或cross-env PORT3000 umi dev团队共享默认端口/缓存开关写入项目根.env仅本地覆盖共享配置新增.env.local不入版本库浏览器端读取变量用UMI_APP_前缀变量或用define手动注入多环境差异化配置使用cross-env UMI_ENVxxx umi dev加载config.xxx.ts调试 bundle 体积ANALYZE1 umi build定位 Webpack 编译慢SPEED_MEASUREJSON umi dev局域网真机调试 HMR设置HOST由 Umi 自动推导SOCKET_SERVER端口被占且要求严格STRICT_PORT8000 umi dev小结环境变量是 Umi 在不修改配置文件的前提下完成临时配置、按环境差异化、按需开关内置能力的最轻量手段。把握三个关键点即可熟练使用注入方式命令行临时赋值跨平台用 cross-env、项目根.env共享与.env.local本地覆盖、.env内支持$VAR变量展开。生效范围默认只在 Node.js 配置环境生效浏览器侧需define注入或使用UMI_APP_前缀约定。能力开关ANALYZE、COMPRESS、HMR、ERROR_OVERLAY、DID_YOU_KNOW、FS_LOGGER、BABEL_POLYFILL、UMI_DEV_SERVER_COMPRESS 等变量统一以none/1之类的值快速启停内置特性而UMI_ENV、UMI_PLUGINS、UMI_PRESETS则负责按环境扩展配置与插件加载。如需深入每个变量的底层行为可继续阅读 packages/core/src/service/env.ts、packages/core/src/config/config.ts 与 packages/bundler-webpack/src/config/definePlugin.ts 的源码实现。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表