Angular 15 环境配置

自 Angular 15 起，ng new 命令不再自动创建 environments 文件夹。本文详解现代化环境配置方案

变更背景

Angular 15 对项目结构进行了简化，移除了自动生成的 environments 文件夹。若仍需使用环境变量，需手动配置或使用推荐的替代方案。

问题描述

在 Angular 14 及更早版本中，创建新项目时会自动生成以下环境文件结构：

src/
└── environments/
    ├── environment.ts       // 开发环境配置
    └── environment.prod.ts  // 生产环境配置

但自 Angular 15 起，使用 ng new 命令创建项目时：

ng new my-app

不再自动创建 environments 文件夹和相关文件，导致开发/生产环境配置缺失。

兼容性提醒

此变更是 Angular 团队有意为之的设计调整，旨在提高项目灵活性：

• ✅ Angular 16/17 延续相同设计
• ⚠️ 直接降级 @angular/cli 到 v14 可恢复旧行为（不推荐）：

npm install -g @angular/cli@14.2.10

解决方案

方案一：使用 Angular CLI 命令生成（官方推荐）

运行以下命令自动创建环境文件并配置 angular.json：

ng generate environments

执行后将生成：

src/
└── environments/
    ├── environment.ts      # 默认环境配置
    └── environment.development.ts

environment.ts

export const environment = {
  production: false
};

environment.development.ts

export const environment = {
  production: true
};

CLI 会自动在 angular.json 中添加生产环境的文件替换规则：

{
  "configurations": {
    "production": {
      // ...其他配置
      "fileReplacements": [
        {
          "replace": "src/environments/environment.ts",
          "with": "src/environments/environment.development.ts"
        }
      ]
    }
  }
}

方案二：手动配置环境

如需要更细粒度的控制，可手动创建环境文件：

1. 创建 environments 文件夹及文件

   src/
   └── environments/
       ├── environment.ts
       ├── environment.prod.ts
       └── environment.staging.ts

2. 编辑 angular.json 添加文件替换规则：

{
  "configurations": {
    "production": {
      "fileReplacements": [
        {
          "replace": "src/environments/environment.ts",
          "with": "src/environments/environment.prod.ts"
        }
      ]
    },
    "staging": {
      "fileReplacements": [
        {
          "replace": "src/environments/environment.ts",
          "with": "src/environments/environment.staging.ts"
        }
      ]
    }
  }
}

3. 构建时指定环境：

ng build --configuration=staging

方案三：动态环境加载（高级方案）

对于需要运行时动态配置的场景（如容器化部署），可使用脚本注入环境变量：

1. 创建脚本 build-scripts/env.js：

const fs = require('fs');
const path = require('path');

// 收集所有 NG_APP_ 开头的环境变量
const envVars = Object.entries(process.env)
  .filter(([key]) => key.startsWith('NG_APP_'))
  .reduce((obj, [key, val]) => ({ ...obj, [key]: val }), {});

// 生成 env.js 文件内容
const fileContent = `
(function(window) {
  window.__env = ${JSON.stringify(envVars, null, 2)};
})(this);
`;

// 写入 src/assets 目录
fs.writeFileSync(
  path.join(__dirname, '../src/assets/env.js'), 
  fileContent
);

2. 在项目中加载生成的脚本：

<!-- index.html -->
<script src="assets/env.js"></script>

3. 在 Angular 组件中访问：

const apiEndpoint = (window as any).__env.NG_APP_API_ENDPOINT;

4. 配置 NPM 脚本确保构建前执行：

{
  "scripts": {
    "prebuild": "node build-scripts/env.js",
    "build": "ng build"
  }
}

项目结构示例

my-app/
├── build-scripts/
│   └── env.js         # 环境生成脚本
├── src/
│   ├── assets/
│   │   └── env.js     # 生成的客户端环境文件
│   ├── environments/  # 可选：传统环境配置
│   └── index.html     # 包含 <script src="assets/env.js">
└── angular.json

最佳实践建议

1. 常规项目
   使用 ng generate environments 官方方案，平衡便捷性和标准化

2. 需要多环境配置时
   手动配置 environment.staging.ts 等文件 + angular.json 多环境设置

3. 云原生/容器化部署
   采用动态环境加载方案，通过环境变量注入配置

4. 项目协作规范

   • 在 .gitignore 中排除生成的文件：

     src/assets/env.js

   • 在文档中明确环境配置方式

注意事项

• 动态方案中使用 window.__env 需注意 XSS 安全风险，仅注入可信数据
• 避免在版本控制中提交敏感信息（如 API 密钥）
• 使用 TypeScript 类型定义增强类型安全：

  // environment.d.ts
  declare interface Window {
    __env: {
      NG_APP_API_ENDPOINT: string;
      NG_APP_VERSION: string;
    };
  }

升级路径建议

对于从 Angular 14 升级的项目：

1. 备份现有环境文件
2. 移除项目中的 environments 文件夹
3. 执行 ng generate environments 重新生成标准化配置
4. 将原配置内容复制到新生成的文件中
5. 验证 angular.json 中的 fileReplacements 规则