vue+node+wabpack|动态环境配置加载技术文档

一、什么问题 (What)

开发场景：
在基于环境变量的多环境配置管理中，遇到以下代码不理解其工作原理：

const api = require(`./${env}/api`).default

具体困惑点：

1. 为什么使用字符串模板拼接路径？
2. require 动态参数如何解析？
3. 为何需要访问 .default 属性？
4. 这种写法与常规导入的区别是什么？

二、为什么出现 (Why)

1. 环境差异化配置需求

• 需要根据 VUE_APP_ENV 环境变量加载对应环境的 API 配置
• 常规静态导入 import 无法实现动态路径

2. CommonJS 模块特性

• require 是运行时动态加载
• 支持字符串拼接路径（import 静态分析不支持此特性）

3. ES Module 兼容问题

• 当目标模块使用 export default 时
• 通过 require 加载会挂载到 default 属性上
• 需显式访问 .default 获取导出对象

4. 历史代码惯用法

• 该写法常见于早期 Webpack 项目
• 用于处理动态环境配置加载

---

三、如何解决 (How)

解决方案

// 1. 获取环境标识
const env = process.env.VUE_APP_ENV || 'dev' 

// 2. 动态加载模块
const apiConfig = require(`./${env}/api`)

// 3. 提取默认导出
const api: ApiType = apiConfig.default

// 4. 合并导出
export default { ...shared, api, env }

关键步骤

1. 环境变量验证
   确保 process.env.VUE_APP_ENV 的值与目录结构匹配（test/pre/online/dev）

2. 路径解析检查

   # 示例：当 env=dev 时
   -> 解析为 ./dev/api.ts
   

3. 模块导出验证
   确认目标文件使用正确导出方式：

   // 正确写法
   export default {
     baseURL: '...',
     endpoints: {...}
   }
   

4. 类型安全增强（可选）

   interface ApiConfig {
     baseURL: string
     timeout: number
     endpoints: Record<string, string>
   }
   const api: ApiConfig = require(...).default
   

---

四、底层原理 (Principle)

1. Node.js 模块加载机制

阶段	说明
路径解析	将模板字符串拼接为完整物理路径
文件查找	按 .js → .ts → .json 顺序查找
模块编译	通过 Webpack/TS-Node 等工具编译
加入缓存	相同路径的模块不会重复加载

2. require 实现原理

function require(path) {
  // 1. 解析绝对路径
  const filename = Module._resolveFilename(path)
  
  // 2. 检查缓存
  if (Module._cache[filename]) {
    return Module._cache.exports
  }

  // 3. 创建模块实例
  const module = new Module(filename)

  // 4. 加载文件内容
  Module._load(filename, module)

  // 5. 返回导出对象
  return module.exports
}

3. ES Module 转换

当遇到 export default 时：

// 原始TS代码
export default { ... }

// 转换为CommonJS
exports.default = { ... }

4. 现代替代方案

// 使用 ES6 动态导入
const loadApiConfig = async () => {
  const module = await import(`./${env}/api`)
  return module.default
}

方案	特点	适用场景
require()	同步加载、立即执行	非模块化环境
import()	异步加载、返回 Promise	现代前端项目
条件导入	静态分析、需明确路径	少量环境分支

---

最佳实践建议：

1. 优先使用 import() 实现动态加载
2. 为环境变量配置 TypeScript 类型声明
3. 使用 __webpack_public_path__ 处理部署路径问题
4. 通过单元测试验证不同环境的配置加载

// 类型声明示例
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      VUE_APP_ENV: 'test' | 'pre' | 'online' | 'dev'
    }
  }
}