工程化

新建项目推荐使用 Angular CLI（@angular/cli），统一生成、构建与测试配置。见生态。

核心概念

Angular CLI 是官方的「一站式」工程工具：项目生成（ng new）、开发服务器（ng serve）、生产构建（ng build）、单测（ng test）、代码生成（ng generate）都由同一个工具完成，底层构建管道基于 esbuild/Vite（现代版本），配置集中在 angular.json。这与 Vue/React 生态中「自由选择 Vite + 各种插件」的方式不同，好处是团队间配置高度一致，代价是深度自定义构建流程的自由度较低。

创建项目

bash

npm install -g @angular/cli
ng new my-app --standalone --routing --style=css
cd my-app
ng serve

文件 / 目录	作用
`angular.json`	构建、测试、样式全局配置
`src/main.ts`	`bootstrapApplication` 入口
`src/app/app.routes.ts`	路由表
`tsconfig.json`	TypeScript 严格选项
`src/app/app.config.ts`	应用级 provider 配置（HttpClient、Router 等）
`public/` 或 `src/assets/`	静态资源（版本相关目录名）

常用 CLI 命令

bash

ng generate component features/user-list   # 生成组件（可简写 ng g c）
ng generate service core/auth              # 生成服务
ng generate guard core/auth                # 生成路由守卫
ng lint                                    # 若已配置 ESLint schematics
ng test                                    # 单元测试
ng e2e                                     # 端到端测试（需先配置）

ng generate 会同时创建组件文件、样式文件、测试文件，并遵循团队在 angular.json 中配置的 schematics 默认项（如统一使用 Standalone、统一样式后缀）。

构建与部署

bash

ng build --configuration production

默认输出到 dist/，为静态文件，可部署到 Nginx、CDN、Firebase Hosting 等。

nginx

# Nginx 部署示例：SPA 路由回退到 index.html
server {
  listen 80;
  root /var/www/my-app/browser;
  location / {
    try_files $uri $uri/ /index.html;
  }
}

环境配置

src/environments/environment.ts 中区分开发与生产 API 地址（CLI 通过 fileReplacements 在构建时替换）。勿将密钥写入前端环境文件。

export const environment = {
  production: false,
  apiUrl: "http://localhost:3000",
};

json

// angular.json（摘录）：production 配置下替换文件
"configurations": {
  "production": {
    "fileReplacements": [
      { "replace": "src/environments/environment.ts", "with": "src/environments/environment.prod.ts" }
    ]
  }
}

依赖注入与应用配置

Standalone 架构下，应用级配置集中在 app.config.ts，替代旧版 AppModule 的 providers：

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(withInterceptors([authInterceptor])),
    provideAnimations(),
  ],
};

// main.ts
bootstrapApplication(AppComponent, appConfig);

SSR 与全栈

Angular SSR（ng add @angular/ssr）支持服务端渲染与混合渲染，适合 SEO 与首屏性能。与纯 SPA 相比部署更复杂（需 Node 或适配的托管）。

bash

ng add @angular/ssr
npm run build          # 生成浏览器与 server 两套产物
node dist/my-app/server/server.mjs

混合渲染（Angular 17+ 的 ServerRoute 配置）允许按路由选择 SSR、预渲染（SSG）或纯客户端渲染，兼顾 SEO 页面与高交互后台页面的不同需求。

与 Vite / React 项目对照

Angular 使用 esbuild/Vite 化构建管道（现代 CLI 版本，以 angular.json 的 builder 为准），并非默认 Vite 配置文件；React + Vite 脚手架更轻。选型按团队规范与是否需要「全家桶」框架决定。

维度	Angular CLI	Vite（Vue/React）
配置文件	`angular.json`（集中式）	`vite.config.ts`（自由插件组合）
生成器	`ng generate` 内置多种 schematics	一般手写或用社区模板
升级路径	`ng update` 自动迁移代码	手动查 changelog 升级依赖
SSR	`ng add @angular/ssr` 官方支持	Next.js / Nuxt 承担

最佳实践

统一用 ng generate 生成文件，保证团队目录结构、命名风格一致。
生产构建务必带 --configuration production，开启压缩、tree-shaking 与预算检查（budgets 配置超限会构建失败，及时排查体积增长）。
环境变量只放非敏感配置（API 基地址等），密钥类信息放后端或构建时注入的 CI 变量，不写入仓库。
升级 Angular 版本用 ng update @angular/core @angular/cli，让官方迁移脚本自动处理破坏性变更。
中大型项目考虑启用 ESLint（ng add @angular-eslint/schematics）与统一的 tsconfig 严格模式。

常见坑

现象	常见原因	处理
生产构建报「超出体积预算」	`angular.json` 中 `budgets` 阈值被触发	分析 bundle，按需拆分或调整合理预算而非直接放宽
部署后刷新子路由 404	服务器未把未知路径回退到 `index.html`	Nginx/静态托管配置 SPA fallback
环境变量在生产环境未生效	`fileReplacements` 配置错误或忘记指定 `--configuration`	检查 `angular.json` 对应 configuration 的 fileReplacements
`ng update` 后编译报错	迁移 schematics 未覆盖全部自定义代码路径	按官方 changelog 手动修正剩余部分
SSR 构建后接口请求报错（无 `window`）	服务端渲染阶段直接使用了浏览器 API	用 `isPlatformBrowser` 判断或延迟到客户端执行

参考文献

以下链接在编写时均可正常访问：

资料	说明
Angular CLI	官方
工作区配置	angular.json
部署	生产部署
Angular SSR	服务端渲染
ng update	版本迁移