HTML本身无构建概念，多环境构建实为借助Webpack、Vite等工具将HTML作为模板参与打包，通过变量注入、路径替换等方式区分环境；需避免手动修改、硬编码，确保环境变量在构建期正确注入HTML与JS中。
HTML 本身没有“构建”概念，所谓多环境构建，本质是用构建工具（如 Webpack、Vite）把 HTML 当作模板参与打包流程，并通过变量注入、路径替换、条件编译等方式区分开发、测试、生产行为。直接写纯 HTML 文件 + 手动改 BASE_API 或 cdnUrl 是不可维护的，也容易漏改、误提交。
Webpack 中用 DefinePlugin 注入环境变量
这是最常用也最容易出错的方式。Webpack 的 DefinePlugin 会在编译时做字符串替换，不是运行时读取 —— 意味着你不能在 JS 里写 if (process.env.NODE_ENV === 'dev') 然后期望它动态生效，它必须是编译期已知的常量。
- 必须用
JSON.stringify()包裹字符串值，否则会报ReferenceError: production is not defined -
process.env.NODE_ENV是 Webpack 内置识别字段，但其他变量（如API_BASE_URL）需显式定义，且 JS 里要写成process.env.API_BASE_URL才能被替换 - HTML 模板中无法直接使用
process.env，需配合html-webpack-plugin的templateParameters或自定义 loader - 别在 .env 文件里写
process.env.NODE_ENV=development—— Webpack 不读 .env，那是 dotenv 库干的事，和 DefinePlugin 无关
Vite 下更简洁的 import.meta.env 用法
Vite 原生支持 import.meta.env，所有以 VITE_ 开头的变量会自动暴露给客户端代码，无需插件配置。但注意：非 VITE_ 前缀的变量（如 NODE_ENV）默认不进前端，只在 Node 端可用。
- 在
.env.development里写VITE_API_BASE=https://api.dev.example.com - JS 中直接用
import.meta.env.VITE_API_BASE，Vite 会在构建时静态替换为字符串字面量 - HTML 模板里不能直接写
%VITE_API_BASE%，得靠vite-plugin-html插件注入，或改用 JS 动态设置document.head - 构建时 Vite 默认只加载
.env和对应环境的.env.[mode]，不会合并多个文件，.env.production和.env.staging互不影响
HTML 模板里的环境判断只能靠构建时预处理
浏览器加载 HTML 是纯静态过程，不存在“运行时判断环境”。想让不同环境加载不同 CDN 脚本、不同 Google Analytics ID 或不同埋点配置，必须在构建阶段生成多个 HTML 文件，或用 JS 动态加载。
- 不要试图在 HTML 里写
<script>if (location.hostname.includes('staging')) {...}</script>—— 这属于运行时逻辑，和“多环境构建”无关，也难测试、易出错 - 推荐方案：用
html-webpack-plugin的templateParameters传参，在 EJS/HTML 模板里用插入值 - 如果用 Vite，可搭配
vite-plugin-html的inject选项，把对象序列化后挂到window.__ENV__，再由 JS 初始化逻辑读取 - 避免在 HTML 中硬编码
https://cdn-prod.example.com，哪怕只是注释掉一行，下次构建也可能被忽略
本地开发 vs 构建产物的路径差异常被忽略
很多人卡在“本地 npm run dev 正常，build 后资源 404”，根本原因是 public/ 目录下文件和构建输出路径没对齐，或 base 配置没设对。
- Webpack 的
output.publicPath和 Vite 的base必须匹配部署路径：部署到子目录（如https://example.com/my-app/）就得设base: '/my-app/'，否则main.js请求地址会变成/main.js（404） -
public/下的文件是直接拷贝的，不走构建流程，所以里面不能放需要环境变量替换的 JSON 或 JS 配置 - 图片等静态资源若放在
src/下，会被 Webpack/Vite 处理并哈希命名；放在public/下则原名保留，适合放 favicon.ico、robots.txt 等固定路径资源 - 别在 HTML 的
<script src="js/app.js"></script>里写相对路径 —— 构建后路径层级可能变，一律用构建工具生成的绝对路径或public/托管
真正麻烦的不是怎么配，而是环境变量从构建工具 → HTML 模板 → 浏览器 JS 的传递链路上，每一环都可能断掉，而且错误不报红、只静默失效。建议每次新增一个环境变量，都在控制台 console.log(import.meta.env) 或 console.log(process.env) 确认它真被注入了，而不是凭感觉写完就跑。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
