Angular CLI 磁盘缓存（cli.cache）配置完全指南：环境控制、路径定制与 `ng cache` 命令实战

• CLI
• 开发工具
• 前端构建
• 构建工具
• 代码生成
• 前端

【免费下载链接】angular-cli

CLI tool for Angular

项目地址：https://gitcode.com/gh_mirrors/an/angular-cli

点击查看免费下载

导读

Angular CLI 默认会把构建过程中的可缓存操作保存到本地磁盘，并在重复构建时直接复用上一次的执行结果，从而显著缩短应用与库的构建、测试耗时。本文以 Angular CLI 官方cache命令的 long-description 文档为核心，结合本仓库（angular-cli）中cache命令源码、workspace 配置 schema 与构建器缓存实现，系统讲解cli.cache配置对象（环境、开关、路径）、CI环境变量的判定机制，以及ng cache enable/disable/clean/info四个子命令的实战用法。读完本文，你将能够精确控制 Angular 工作区中磁盘缓存的启用时机、存储位置与清理方式。

一、缓存机制：Angular CLI 默认的磁盘持久化

按官方 long-description 文档（packages/angular/cli/src/commands/cache/long-description.md）的说明，Angular CLI默认会在磁盘上保存一系列可缓存的操作（cachable operations）。当你再次运行相同的构建时，构建系统会恢复上一次构建的状态，并复用之前已执行过的操作，从而缩短构建和测试应用、库所需的时间。

这意味着在大多数场景下，你无需任何额外配置就能享受增量构建带来的提速——例如 webpack 的 babel 编译缓存、Angular 编译器的中间产物等都会被持久化到本地磁盘，供后续命令复用。

二、配置入口：在 Workspace 配置中声明cli.cache

2.1 配置位置与完整示例

默认缓存设置可以通过在Workspace 配置（即angular.json）中添加cli.cache对象来修改。该对象位于配置文件顶层的cli字段下，必须放在projects区块之外：

{ "$schema": "./node_modules/@angular/cli/lib/config/schema.json", "version": 1, "cli": { "cache": { // ... }, }, "projects": {}, }

当前仓库中与此对应的 JSON Schema 定义位于 packages/angular/cli/lib/config/workspace-schema.json（cli.cache小节），它明确了cache对象支持的全部属性及其类型：

属性	类型	默认值	说明
enabled	boolean	true	是否启用磁盘缓存
environment	string	local	缓存生效的环境，枚举值为local、ci、all
path	string	.angular/cache	缓存的基础路径（base path）

注意 Schema 中additionalProperties被设为false，因此不能随意添加未知属性，否则配置校验会失败。

2.2 读取逻辑与默认值兜底

从源码实现看，packages/angular/cli/src/commands/cache/utilities.ts 中的getCacheConfig()函数按以下优先级读取配置：

1. 读取workspace.extensions['cli']，若不是 JSON 对象则整体回退到默认值；
2. 再读取cli['cache']，同样需为 JSON 对象；
3. 对path、environment、enabled三个字段逐一做默认值兜底（分别为.angular/cache、local、true）。

也就是说，即使你的angular.json完全没有配置cli.cache，构建系统依然会按照上述默认值启用本地磁盘缓存。

三、缓存环境（Cache environments）：精确控制缓存的生效范围

3.1 三种环境的语义

按官方文档，磁盘缓存默认只在本地（local）环境启用。environment的取值及其语义如下：

• all：在所有机器上启用磁盘缓存（包括本地开发机与 CI 机器）；
• local：仅在开发机器上启用磁盘缓存（CI 机器上自动关闭）；
• ci：仅在持续集成（CI）系统上启用磁盘缓存（本地开发机自动关闭）。

三种模式的核心价值在于避免缓存带来的环境差异：例如在 CI 上，机器间共享工作区、缓存内容可能与构建上下文不匹配，默认的local模式可以让 CI 自动绕开磁盘缓存。

3.2 CI 环境判定：CI环境变量

官方 long-description 用一个提示框特别强调：

The Angular CLI checks for the presence and value of theCIenvironment variable to determine in which environment it is running.（Angular CLI 会检查CI环境变量的存在与取值，以判断当前运行在何种环境。）

这一判定逻辑在仓库中有两处实现佐证：

• 在 packages/angular/cli/src/utilities/environment-options.ts 中，isCI由parseTristate(process.env['CI']) === true得出——只有CI取值为1或true（不区分大小写）时才认定为 CI 环境；
• 在构建器侧 packages/angular_devkit/build_angular/src/utils/normalize-cache.ts 中，同样通过process.env['CI']判断isCI，然后依据environment计算cacheEnabled：ci模式只在 CI 上启用，local模式只在非 CI 上启用，all模式始终启用。

3.3 修改环境：命令行与手改配置

要把环境设置改为all，可以直接在终端执行（命令作用于当前工作区的angular.json）：

ng config cli.cache.environment all

该命令等价于在angular.json中写入：

{ "cli": { "cache": { "environment": "all" } } }

在 packages/angular/cli/src/commands/cache/utilities.ts 的updateCacheConfig()中可以看到，这类修改通过workspace.extensions['cli']上就地创建/更新cache对象并调用workspace.save()落盘，因此ng config是安全、受 Schema 校验的官方修改途径。

四、缓存路径（Cache path）：定制缓存存储位置

4.1 默认路径与修改命令

按官方文档，默认情况下.angular/cache被用作存储缓存结果的基础目录（base directory）。如果想改为.cache/ng，执行：

ng config cli.cache.path ".cache/ng"

注意命令中的路径参数带引号，以避免 shell 对点号开头目录名的解析歧义。

4.2 路径解析的细节：Git Worktree 支持与版本化子目录

修改后的相对路径并不是简单拼在angular.json所在目录下，仓库源码揭示了更精细的解析规则：

• packages/angular/cli/src/commands/cache/utilities.ts 中的getCacheBasePath()会：如果配置的是绝对路径，直接采用；否则从工作区根目录向上逐级查找.git，若发现是 Git worktree（.git为包含gitdir:指令的普通文件且存在commondir），则把缓存目录解析到该 worktree 的公共 Git 目录附近，保证同一仓库的多个 worktree 共享同一份缓存；
• 构建器侧 packages/angular_devkit/build_angular/src/utils/normalize-cache.ts 在基础路径下还会追加版本号子目录（例如/.angular/cache/v17.0.0），让不同 CLI 大版本之间的缓存互不污染，升级后自动失效重建。

因此，当你在ng cache info中看到的 "Path" 与磁盘上真实目录可能存在版本号层级差异，这是设计使然。

五、缓存运维命令：ng cache子命令实战

cache是 Angular CLI 的一级命令（定义于 packages/angular/cli/src/commands/cache/cli.ts，描述为 "Configure persistent disk cache and retrieve cache statistics."），它本身没有独立动作，必须配合下列子命令使用（demandCommand(1)强制要求子命令）：

5.1ng cache enable/ng cache disable

• ng cache enable（别名on）：为工作区中所有项目启用磁盘缓存；
• ng cache disable（别名off）：为工作区中所有项目禁用磁盘缓存。

实现位于 packages/angular/cli/src/commands/cache/settings/cli.ts，本质是调用updateCacheConfig(workspace, 'enabled', true/false)写入cli.cache.enabled。

5.2ng cache clean

删除磁盘上的持久化缓存（实现见 packages/angular/cli/src/commands/cache/clean/cli.ts）。它读取cli.cache.path解析出的实际目录，然后以force: true, recursive: true, maxRetries: 3的方式递归删除。当你怀疑缓存损坏（例如出现奇怪的编译错误、产物不更新）时，这是首选排障手段。

5.3ng cache info

在控制台打印磁盘缓存的配置与统计信息（实现见 packages/angular/cli/src/commands/cache/info/cli.ts），典型输出包含：

Cache Information Enabled : Yes Environment : local Path : /path/to/workspace/.angular/cache Size on disk : 123.45 MB Effective Status : Enabled (current machine)

其中Effective Status（当前机器的实际生效状态）值得特别关注：它会根据environment与isCI计算（info/cli.ts）——例如environment为local而当前处于 CI 时，虽然Enabled显示Yes，但Effective Status会显示Disabled (current machine)。这解释了为什么配置看起来已开启、构建却未命中缓存：环境限制在起作用。

六、缓存与构建流程的衔接

缓存配置不只影响ng cache命令本身，还会被构建器读取并注入实际构建工具。在 packages/angular_devkit/build_angular/src/tools/webpack/configs/common.ts 中可以看到，webpack 配置的cacheDirectory被设置为(cache.enabled && path.join(cache.path, 'babel-webpack')) || false——即只有缓存启用时才为 babel-loader 提供babel-webpack子目录作为编译缓存目录，否则显式关闭。

也就是说，cli.cache的启停状态会直接影响 webpack/babel 等底层工具的实际缓存行为，这正是"复用已执行操作、减少构建时间"的具体落地路径。

七、常见问题与最佳实践

1. CI 上缓存未生效：确认angular.json中cli.cache.environment是否为all（或ci），并用ng cache info查看Effective Status；多数 CI 平台默认已设置CI=true，满足local模式自动关闭的判断条件。
2. 修改路径后旧缓存未清理：cli.cache.path只影响后续缓存写入位置，旧目录不会自动删除，可手动删除或执行ng cache clean后再按新路径重建。
3. 遇到诡异构建结果：优先执行ng cache clean清除可能损坏的缓存，再重新构建；clean使用force: true，即使目录不存在也不会报错。
4. 多 Git worktree 场景：缓存路径会解析到公共 Git 目录附近以共享缓存（见 utilities.ts 的 worktree 处理逻辑），无需手工为每个 worktree 单独配置路径。
5. 升级 CLI 大版本：缓存目录按版本号隔离（normalize-cache.ts），旧版本缓存自动失效，无需手动清理。

通过合理配置cli.cache.environment、enabled与path，再配合ng cache enable/disable/clean/info四个子命令，你可以在本地开发与 CI 流水线中精确掌控 Angular CLI 的磁盘缓存行为，在保证结果正确性的前提下最大化构建与测试的复用效率。

赞分享

• CLI
• 开发工具
• 前端构建
• 构建工具
• 代码生成
• 前端

【免费下载链接】angular-cli

CLI tool for Angular

项目地址：https://gitcode.com/gh_mirrors/an/angular-cli

点击查看免费下载

相关推荐

• Ollama HTTP缓存控制：ETag与Cache-Control配置完全指南

  Ollama HTTP缓存控制：ETag与Cache Control配置完全指南 想要优化Ollama大语言模型本地部署的性能？掌握HTTP缓存控制是提升响应速

  人工智能大模型模型推理服务本地部署后端LLM 网关

• mise cache clear 命令完全指南：清理工具缓存、任务输出缓存与环境缓存

  mise cache clear 命令完全指南：清理工具缓存、任务输出缓存与环境缓存 mise cache clear 是 mise（dev tools、env

  开发工具CLI

• Nautilus Trader 缓存机制完全指南：Cache 架构、配置与实战调用

  Nautilus Trader 缓存机制完全指南：Cache 架构、配置与实战调用 本文是 Nautilus Trader 事件驱动交易引擎中 Cache 组件

  金融科技后端

上一篇：突破AI响应瓶颈：Pydantic AI流式处理与工具调用全解析

下一篇：IsaacLab CloudXR 远程可视化连不上？4 类典型故障的排查与修复