Nx 17.0.0 缓存目录迁移指南从node_modules/.cache/nx到.nx/cache【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本文基于 Nx 官方仓库中move-cache-directory.md迁移文档深入讲解 Nx 17.0.0 将默认任务缓存目录迁移到.nx/cache的背景、自动迁移机制、.gitignore/.prettierignore的同步处理以及手工迁移的完整步骤。读完本文你将理解 Nx 缓存目录的解析逻辑与底层实现并掌握在任何工作区中正确配置、忽略和验证.nx/cache的实战能力。一、为什么 Nx 17.0.0 要移动缓存目录从 Nx 17.0.0 起Nx 的默认缓存目录由原来的node_modules/.cache/nx迁移为工作区根目录下的.nx/cache。这一调整是 Nx 对工作区本地数据统一归置的一部分——缓存不再与node_modules耦合而是集中存放于独立的.nx目录中。在官方迁移注册表 packages/nx/migrations.json 中本次迁移被登记为17.0.0-move-cache-directory: { cli: nx, version: 17.0.0-beta.1, description: Updates the default cache directory to .nx/cache, implementation: ./dist/src/migrations/update-17-0-0/move-cache-directory, documentation: ./dist/src/migrations/update-17-0-0/move-cache-directory.md }可见其官方描述正是Updates the default cache directory to .nx/cache版本门槛为17.0.0-beta.1说明该变更在 17.0.0 开发周期早期就已落地。二、迁移源码剖析迁移器到底做了什么迁移的实际逻辑位于 packages/nx/src/migrations/update-17-0-0/move-cache-directory.ts完整流程如下export default function moveCacheDirectory(tree: Tree) { // 若仓库只有 lerna.json 而没有 nx.json则跳过迁移 if (tree.exists(lerna.json) !tree.exists(nx.json)) { return; } updateGitIgnore(tree); if (tree.exists(.prettierignore)) { const ignored tree.read(.prettierignore, utf-8); if (!ignored.includes(.nx/cache)) { tree.write(.prettierignore, [ignored, /.nx/cache].join(\n)); } } }1. Lerna 特例不强制迁移迁移器首先检查lerna.json是否存在且nx.json不存在。若满足该条件则直接返回。源码注释解释了原因如果仓库没有nx.json则无法利用 Nx 缓存.nx/cache意义不大对于尚未完全切换到 Nx 的 Lerna 用户突然出现.nx目录可能造成困扰。这条特例逻辑在cache-directory.ts的运行时解析中也有完全一致的对应实现if ( existsSync(join(root, lerna.json)) !existsSync(join(root, nx.json)) ) { return join(root, node_modules, .cache, nonNxCacheDirectory); } return join(root, .nx, nxCacheDirectory);也就是说运行时与迁移器对 Lerna 场景的判断保持一致——纯 Lerna 仓库继续使用node_modules/.cache/nx只有真正启用了 Nx存在nx.json的仓库才使用.nx/cache。这保证了迁移器不会对不适用新缓存路径的仓库做无意义修改。2. 更新.gitignore基于 ignore 库的智能判断迁移器调用updateGitIgnore处理.gitignorefunction updateGitIgnore(tree: Tree) { const gitignore tree.exists(.gitignore) ? tree.read(.gitignore, utf-8) : ; const ig ignore(); ig.add(gitignore); if (!ig.ignores(.nx/cache)) { const updatedLines gitignore.length ? [gitignore, .nx/cache] : [.nx/cache]; tree.write(.gitignore, updatedLines.join(\n)); } }值得注意的实现细节迁移器使用ignore库解析现有.gitignore规则再判断.nx/cache是否已经被现有规则覆盖例如已有的.*/cache或.nx/模式。只有未被覆盖时才追加.nx/cache行避免产生重复或冗余规则。3. 更新.prettierignore仅在文件存在时追加对.prettierignore的处理更保守仅当文件已存在时才读取并追加/.nx/cache注意带前导/表示仓库根目录下的精确路径且同样先检查是否已包含.nx/cache以避免重复写入。若.prettierignore不存在则不做任何创建。三、官方文档中的样例变更原文档核心move-cache-directory.md文档给出了两个标准的手工修改样例与迁移器行为一一对应。样例 1在.gitignore中添加.nx/cacheBefore迁移前node_modulesAfter迁移后node_modules .nx/cache样例 2在.prettierignore中添加.nx/cacheBefore迁移前/distAfter迁移后/dist .nx/cache这两处改动确保了缓存目录不会污染 Git 提交也不会被 Prettier 格式化遍历。四、测试验证迁移器行为的 7 个边界场景迁移器的全部行为都由单元测试覆盖测试文件位于 packages/nx/src/migrations/update-17-0-0/move-cache-directory.spec.ts共 7 个用例场景前置状态预期行为向 gitignore 添加缓存目录.gitignore内容为node_modules追加为node_modules\n.nx/cache.gitignore不存在文件被删除新建文件内容仅为.nx/cache已直接忽略.gitignore已有node_modules\n.nx/cache不重复追加保持原样已被其他模式忽略.gitignore已有.*/cache不追加智能识别Lerna 仓库无 nx.json存在lerna.json且无nx.json完全不修改.gitignore处理 prettierignore.prettierignore内容为/dist追加为/dist\n/.nx/cacheprettierignore 不存在文件被删除不创建文件这些测试直接印证了迁移器幂等、智能、保守的设计重复运行不会产生重复条目已有通配规则会覆盖新路径纯 Lerna 仓库不受影响。五、运行时如何解析缓存目录底层原理迁移之后Nx 在每次运行时是如何确定缓存目录位置的答案在 packages/nx/src/utils/cache-directory.ts 中。1. 默认解析链function cacheDirectory(root: string, cacheDirectory: string) { const cacheDirFromEnv process.env.NX_CACHE_DIRECTORY; if (cacheDirFromEnv) { cacheDirectory cacheDirFromEnv; } if (cacheDirectory) { return absolutePath(root, cacheDirectory); } else { return defaultCacheDirectory(root); } }解析优先级从高到低为环境变量NX_CACHE_DIRECTORY最高优先级适用于 CI 或临时覆盖场景配置文件cacheDirectory读取nx.json中的cacheDirectory字段或旧的tasksRunnerOptions.default.options.cacheDirectory见readCacheDirectoryProperty默认值workspaceRoot/.nx/cacheLerna 特例为node_modules/.cache/nx。2.nx.json中的配置入口在 packages/nx/src/config/nx-json.ts 中cacheDirectory是NxJsonConfiguration的公开配置项/** * Changes the directory used by Nx to store its cache. */ cacheDirectory?: string;需要自定义缓存位置的工作区可在nx.json中配置{ cacheDirectory: .cache/nx-custom }该配置需与默认值一样通过.gitignore忽略可通过.nx/cache之外的规则例如.cache/。3. 环境变量NX_CACHE_DIRECTORY在 CI 或需要临时隔离缓存的场景下可通过环境变量强制指定NX_CACHE_DIRECTORY/tmp/nx-cache nx build my-app环境变量的优先级高于nx.json中的cacheDirectory配置。六、手工迁移与验证完整操作步骤若你的工作区因某些原因未自动执行迁移例如使用了旧版 Nx 或手动管理的仓库可按下述步骤手工迁移步骤 1确认当前缓存位置# 查看当前缓存目录若显示 node_modules/.cache/nx 则需要迁移 nx reset --help # 观察 .nx 目录是否已生成 ls -la .nx步骤 2更新.gitignore在.gitignore末尾追加一行.nx/cache步骤 3更新.prettierignore若存在该文件在.prettierignore末尾追加/.nx/cache步骤 4清理旧缓存并验证# 触发迁移升级到 Nx 17 后运行 nx migrate latest # 验证缓存写入新位置 nx build my-app ls .nx/cache若看到.nx/cache下生成了哈希命名的缓存文件说明迁移成功。七、清理缓存nx reset与缓存目录的关系迁移后nx reset命令会同时清理新旧两种路径下的缓存。在 packages/nx/src/command-line/reset/reset.ts 中有明确注释rmSync(cacheDir, { recursive: true, force: true }); // cacheDir is the shared directory whenever sharing is available, so // this is the checkouts own .nx/cache: still there from before the // move, and still what a later run falls back to if ~/.nx stops being // available. removeIfDistinct(cacheDirectoryForWorkspace(workspaceRoot), cacheDir);可见 Nx 在清理时会同时处理共享缓存与工作区自身的.nx/cache确保升级迁移期间产生的旧缓存残留也能被清除。八、总结Nx 17.0.0 的缓存目录迁移是 Nx 将缓存从node_modules解耦、归入.nx目录的重要一步迁移器move-cache-directory.ts自动为.gitignore追加.nx/cache、为已有的.prettierignore追加/.nx/cache智能幂等使用 ignore 库判断是否已被现有规则覆盖重复运行不会产生重复条目Lerna 特例纯 Lerna 仓库无nx.json不迁移保持node_modules/.cache/nx运行时一致性cache-directory.ts中的默认路径解析与迁移器共享同一套判断逻辑确保迁移前后行为一致可配置性可通过nx.json的cacheDirectory或环境变量NX_CACHE_DIRECTORY自定义缓存位置。无论你是刚刚升级到 Nx 17 的存量用户还是需要手工管理缓存目录的维护者遵循.gitignore添加.nx/cache、.prettierignore添加/.nx/cache两条规则即可保证工作区干净、缓存可复现。/output文章【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Nx 17.0.0 缓存目录迁移指南从node_modules/.cache/nx到.nx/cache【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本文基于 Nx 官方仓库中move-cache-directory.md迁移文档深入讲解 Nx 17.0.0 将默认任务缓存目录迁移到.nx/cache的背景、自动迁移机制、.gitignore/.prettierignore的同步处理以及手工迁移的完整步骤。读完本文你将理解 Nx 缓存目录的解析逻辑与底层实现并掌握在任何工作区中正确配置、忽略和验证.nx/cache的实战能力。一、为什么 Nx 17.0.0 要移动缓存目录从 Nx 17.0.0 起Nx 的默认缓存目录由原来的node_modules/.cache/nx迁移为工作区根目录下的.nx/cache。这一调整是 Nx 对工作区本地数据统一归置的一部分——缓存不再与node_modules耦合而是集中存放于独立的.nx目录中。在官方迁移注册表 packages/nx/migrations.json 中本次迁移被登记为17.0.0-move-cache-directory: { cli: nx, version: 17.0.0-beta.1, description: Updates the default cache directory to .nx/cache, implementation: ./dist/src/migrations/update-17-0-0/move-cache-directory, documentation: ./dist/src/migrations/update-17-0-0/move-cache-directory.md }可见其官方描述正是Updates the default cache directory to .nx/cache版本门槛为17.0.0-beta.1说明该变更在 17.0.0 开发周期早期就已落地。二、迁移源码剖析迁移器到底做了什么迁移的实际逻辑位于 packages/nx/src/migrations/update-17-0-0/move-cache-directory.ts完整流程如下export default function moveCacheDirectory(tree: Tree) { // 若仓库只有 lerna.json 而没有 nx.json则跳过迁移 if (tree.exists(lerna.json) !tree.exists(nx.json)) { return; } updateGitIgnore(tree); if (tree.exists(.prettierignore)) { const ignored tree.read(.prettierignore, utf-8); if (!ignored.includes(.nx/cache)) { tree.write(.prettierignore, [ignored, /.nx/cache].join(\n)); } } }1. Lerna 特例不强制迁移迁移器首先检查lerna.json是否存在且nx.json不存在。若满足该条件则直接返回。源码注释解释了原因如果仓库没有nx.json则无法利用 Nx 缓存.nx/cache意义不大对于尚未完全切换到 Nx 的 Lerna 用户突然出现.nx目录可能造成困扰。这条特例逻辑在cache-directory.ts的运行时解析中也有完全一致的对应实现if ( existsSync(join(root, lerna.json)) !existsSync(join(root, nx.json)) ) { return join(root, node_modules, .cache, nonNxCacheDirectory); } return join(root, .nx, nxCacheDirectory);也就是说运行时与迁移器对 Lerna 场景的判断保持一致——纯 Lerna 仓库继续使用node_modules/.cache/nx只有真正启用了 Nx存在nx.json的仓库才使用.nx/cache。这保证了迁移器不会对不适用新缓存路径的仓库做无意义修改。2. 更新.gitignore基于 ignore 库的智能判断迁移器调用updateGitIgnore处理.gitignorefunction updateGitIgnore(tree: Tree) { const gitignore tree.exists(.gitignore) ? tree.read(.gitignore, utf-8) : ; const ig ignore(); ig.add(gitignore); if (!ig.ignores(.nx/cache)) { const updatedLines gitignore.length ? [gitignore, .nx/cache] : [.nx/cache]; tree.write(.gitignore, updatedLines.join(\n)); } }值得注意的实现细节迁移器使用ignore库解析现有.gitignore规则再判断.nx/cache是否已经被现有规则覆盖例如已有的.*/cache或.nx/模式。只有未被覆盖时才追加.nx/cache行避免产生重复或冗余规则。3. 更新.prettierignore仅在文件存在时追加对.prettierignore的处理更保守仅当文件已存在时才读取并追加/.nx/cache注意带前导/表示仓库根目录下的精确路径且同样先检查是否已包含.nx/cache以避免重复写入。若.prettierignore不存在则不做任何创建。三、官方文档中的样例变更原文档核心move-cache-directory.md文档给出了两个标准的手工修改样例与迁移器行为一一对应。样例 1在.gitignore中添加.nx/cacheBefore迁移前node_modulesAfter迁移后node_modules .nx/cache样例 2在.prettierignore中添加.nx/cacheBefore迁移前/distAfter迁移后/dist .nx/cache这两处改动确保了缓存目录不会污染 Git 提交也不会被 Prettier 格式化遍历。四、测试验证迁移器行为的 7 个边界场景迁移器的全部行为都由单元测试覆盖测试文件位于 packages/nx/src/migrations/update-17-0-0/move-cache-directory.spec.ts共 7 个用例场景前置状态预期行为向 gitignore 添加缓存目录.gitignore内容为node_modules追加为node_modules\n.nx/cache.gitignore不存在文件被删除新建文件内容仅为.nx/cache已直接忽略.gitignore已有node_modules\n.nx/cache不重复追加保持原样已被其他模式忽略.gitignore已有.*/cache不追加智能识别Lerna 仓库无 nx.json存在lerna.json且无nx.json完全不修改.gitignore处理 prettierignore.prettierignore内容为/dist追加为/dist\n/.nx/cacheprettierignore 不存在文件被删除不创建文件这些测试直接印证了迁移器幂等、智能、保守的设计重复运行不会产生重复条目已有通配规则会覆盖新路径纯 Lerna 仓库不受影响。五、运行时如何解析缓存目录底层原理迁移之后Nx 在每次运行时是如何确定缓存目录位置的答案在 packages/nx/src/utils/cache-directory.ts 中。1. 默认解析链function cacheDirectory(root: string, cacheDirectory: string) { const cacheDirFromEnv process.env.NX_CACHE_DIRECTORY; if (cacheDirFromEnv) { cacheDirectory cacheDirFromEnv; } if (cacheDirectory) { return absolutePath(root, cacheDirectory); } else { return defaultCacheDirectory(root); } }解析优先级从高到低为环境变量NX_CACHE_DIRECTORY最高优先级适用于 CI 或临时覆盖场景配置文件cacheDirectory读取nx.json中的cacheDirectory字段或旧的tasksRunnerOptions.default.options.cacheDirectory见readCacheDirectoryProperty默认值workspaceRoot/.nx/cacheLerna 特例为node_modules/.cache/nx。2.nx.json中的配置入口在 packages/nx/src/config/nx-json.ts 中cacheDirectory是NxJsonConfiguration的公开配置项/** * Changes the directory used by Nx to store its cache. */ cacheDirectory?: string;需要自定义缓存位置的工作区可在nx.json中配置{ cacheDirectory: .cache/nx-custom }该配置需与默认值一样通过.gitignore忽略可通过.nx/cache之外的规则例如.cache/。3. 环境变量NX_CACHE_DIRECTORY在 CI 或需要临时隔离缓存的场景下可通过环境变量强制指定NX_CACHE_DIRECTORY/tmp/nx-cache nx build my-app环境变量的优先级高于nx.json中的cacheDirectory配置。六、手工迁移与验证完整操作步骤若你的工作区因某些原因未自动执行迁移例如使用了旧版 Nx 或手动管理的仓库可按下述步骤手工迁移步骤 1确认当前缓存位置# 查看当前缓存目录若显示 node_modules/.cache/nx 则需要迁移 nx reset --help # 观察 .nx 目录是否已生成 ls -la .nx步骤 2更新.gitignore在.gitignore末尾追加一行.nx/cache步骤 3更新.prettierignore若存在该文件在.prettierignore末尾追加/.nx/cache步骤 4清理旧缓存并验证# 触发迁移升级到 Nx 17 后运行 nx migrate latest # 验证缓存写入新位置 nx build my-app ls .nx/cache若看到.nx/cache下生成了哈希命名的缓存文件说明迁移成功。七、清理缓存nx reset与缓存目录的关系迁移后nx reset命令会同时清理新旧两种路径下的缓存。在 packages/nx/src/command-line/reset/reset.ts 中有明确注释rmSync(cacheDir, { recursive: true, force: true }); // cacheDir is the shared directory whenever sharing is available, so // this is the checkouts own .nx/cache: still there from before the // move, and still what a later run falls back to if ~/.nx stops being // available. removeIfDistinct(cacheDirectoryForWorkspace(workspaceRoot), cacheDir);可见 Nx 在清理时会同时处理共享缓存与工作区自身的.nx/cache确保升级迁移期间产生的旧缓存残留也能被清除。八、总结Nx 17.0.0 的缓存目录迁移是 Nx 将缓存从node_modules解耦、归入.nx目录的重要一步迁移器move-cache-directory.ts自动为.gitignore追加.nx/cache、为已有的.prettierignore追加/.nx/cache智能幂等使用 ignore 库判断是否已被现有规则覆盖重复运行不会产生重复条目Lerna 特例纯 Lerna 仓库无nx.json不迁移保持node_modules/.cache/nx运行时一致性cache-directory.ts中的默认路径解析与迁移器共享同一套判断逻辑确保迁移前后行为一致可配置性可通过nx.json的cacheDirectory或环境变量NX_CACHE_DIRECTORY自定义缓存位置。无论你是刚刚升级到 Nx 17 的存量用户还是需要手工管理缓存目录的维护者遵循.gitignore添加.nx/cache、.prettierignore添加/.nx/cache两条规则即可保证工作区干净、缓存可复现。/output文章【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
机制深度解析与实践)
)
)
