AIRI 仓库实践：pnpm 11 配置模型迁移指南——从 pnpm-workspace.yaml 到全局 config.yaml 与 .npmrc 权限边界

人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本指南以 AIRI 仓库的 pnpm 技能文档.agents/skills/pnpm/references/core-config.md为主体结合仓库根目录真实配置 pnpm-workspace.yaml 与 package.json 展开讲解。AIRI 是自托管的 AI 伴侣与赛博生命灵魂容器项目采用 pnpm 11 管理的超大型 monorepopackages/、apps/、server/、engines/、plugins/、integrations/、services/、docs/等数十个子项目。读完本文你将彻底掌握 pnpm 11 的双文件配置模型哪些设置进pnpm-workspace.yaml、哪些进全局config.yaml、哪些只能留在.npmrc并学会用packageConfigs做包级配置、用pnpm config --locationproject写配置、用devEngines固定 Node 版本。一、pnpm 11 配置模型最关键的认知转变pnpm 的所有设置被明确拆分为两个大类弄清每种设置该放哪里是使用当前 pnpm 最重要的一课类别存放位置格式全部 pnpm / install 设置nodeLinker、hoistPattern、autoInstallPeers、overrides、catalog等pnpm-workspace.yaml项目级与config.yaml全局级YAMLcamelCase键名认证与 registry 凭据_authToken、cert、key等.npmrc项目级已 gitignore与全局rc文件INI需要特别注意两处重大变更pnpm 不再读取package.json的pnpm字段。旧项目写在package.json#pnpm里的overrides、patchedDependencies、onlyBuiltDependencies等全部失效必须迁移到pnpm-workspace.yaml。.npmrc现在只用于认证 / registry 凭据。其余一切设置属于pnpm-workspace.yaml且 YAML 键名使用camelCase如nodeLinker不再是旧.npmrc时代的 kebab-case如node-linker。AIRI 仓库恰好是这一模型的典型实践根目录只有一份 pnpm-workspace.yaml约 580 行集中承载了 workspace 声明、catalog、overrides、patchedDependencies、allowBuilds、packageExtensions、minimumReleaseAge 等全部非凭据设置根目录没有.npmrc文件认证凭据交由开发者本地维护并保持 gitignore。二、pnpm-workspace.yaml主配置文件的完整解剖该文件位于工作区 / 项目根目录。即使是单包项目pnpm 也使用它存放设置。以下是一份完整的最小示例# Workspace packages (单包仓库可省略) packages: - packages/* - apps/* - !**/test/** # 常用 install 设置camelCase nodeLinker: isolated # isolated默认| hoisted | pnp autoInstallPeers: true strictPeerDependencies: false savePrefix: ^ saveExact: false hoistPattern: - *eslint* - *babel* publicHoistPattern: [] shamefullyHoist: false dedupeDirectDeps: false resolutionMode: highest # highest | time-based | lowest-direct # 集中式版本管理 catalog: react: ^18.2.0 # 强制依赖版本仅限根目录 overrides: lodash: ^4.17.21 foo^1.0.0bar: ^2.0.0 # 扩展 / 修补有问题的包清单 packageExtensions: react-redux: peerDependencies: react-dom: * # Peer 依赖规则 peerDependencyRules: ignoreMissing: - babel/* allowedVersions: react: 17 || 182.1 从源码看 AIRI 的真实用法对照上述骨架AIRI 的 pnpm-workspace.yaml 展示了大型 monorepo 的进阶组合packages 的 glob 与排除packages/**、plugins/**、integrations/**、services/**、examples/**、docs/**、engines/**、apps/**、server/**并用!**/dist/**排除构建产物目录。shellEmulator: true为安装脚本提供 POSIX 风格的 shell 模拟。仓库注释记录了一个典型权衡——在shellEmulator: true且没有.git目录时simple-git-hooks的 install 可能失败因此 pnpm-workspace.yaml 中simple-git-hooks: false。catalog与命名catalogs根catalog收纳了数百个共享依赖vue、vite、typescript、unocss等同时还定义了命名目录vitest与xsai供各子包通过catalog:vitest、catalog:xsai引用见 pnpm-workspace.yaml。overrides的多形态既有无条件覆盖如hono: 4.13.3、catalog:引用types/hast: catalog:也有npm:别名替换axios: npm:feaxios^0.0.23、链式嵌套覆盖eslint-plugin-sonarjstypescript: catalog:以及用nolyfill/*替换一堆原生 polyfill 包的做法见 pnpm-workspace.yaml。patchedDependencies把六个第三方包打到patches/目录下例如xsai-ext/responses0.5.1: patches/xsai-ext__responses0.5.1.patch、mineflayer-pathfinder: patches/mineflayer-pathfinder.patch对应仓库 patches 目录中的实际补丁文件。allowBuilds以单一映射表审批几十个需要执行安装脚本的包electron、esbuild、canvas、isolated-vm、sharp、onnxruntime-node等见 pnpm-workspace.yaml。packageExtensions为pixiv/three-vrm-*、tresjs/core、vitepress、vue-sonner等包补充缺失的 peer 声明见 pnpm-workspace.yaml。这些配置在pnpm-lock.yaml顶部有直接印证settings: autoInstallPeers: true且catalogs: default节点完整镜像了 workspace 中的catalog条目。三、全局配置config.yaml与全局 rc 文件用户级非认证设置存放在全局 YAMLconfig.yaml中位置取决于操作系统$XDG_CONFIG_HOME/pnpm/config.yaml若设置了该环境变量Linux~/.config/pnpm/config.yamlmacOS~/Library/Preferences/pnpm/config.yamlWindows~/AppData/Local/pnpm/config/config.yaml同目录下名为rc的伴生全局文件只存放 registry / 认证设置。这套全局也分两份的设计与项目级完全一致YAML 管设置、INI 管凭据。四、工作区内的包级配置packageConfigspnpm 11 下不再存在子项目各自的.npmrc。若想为某个子包单独设置使用根pnpm-workspace.yaml中的packageConfigspackageConfigs: # Map 形式以包名为键 project-1: saveExact: true project-2: savePrefix: ~ # Array 形式按模式匹配的规则 # - match: [project-1, project-2] # modulesDir: node_modules # saveExact: true配合 core-workspaces.md 中的描述可知packageConfigs是 v10→v11 迁移时由逐子项目.npmrc机械转换而来的packageConfigs[name]因此老项目迁移后应重点检查这一节是否完整继承。五、.npmrc只留认证与 registry 凭据认证 token 绝不能提交进仓库——项目级.npmrc应保持在 gitignore 状态。认证文件的优先级从高到低为workspace root/.npmrc项目级gitignoredpnpm config/auth.ini由pnpm login写入~/.npmrc为 npm 兼容性保留的兜底//registry.npmjs.org/:_authToken${NPM_TOKEN} myorg:registryhttps://npm.myorg.com/ //npm.myorg.com/:_authToken${MYORG_TOKEN}而非敏感的 registry 地址本身应配置在pnpm-workspace.yaml中registries: default: https://registry.npmjs.org/ my-org: https://private.example.com/ # 命名的 registry 别名可作为包名前缀使用如 pnpm add work:corp/lib namedRegistries: work: https://npm.work.example.com/安全提示v11 起生效自 pnpm 11 起项目级.npmrc中的 registry / proxy URL 与凭据键不再做环境变量展开——这是为了防止恶意仓库通过.npmrc窃取本地密钥。因此动态 token 行应写入用户级认证文件如auth.ini而不是项目.npmrc。六、pnpm config 命令读写两类配置# 默认写入全局 config.yaml / rc pnpm config set nodeVersion 22.0.0 pnpm config set --locationproject nodeVersion 22.0.0 # 写入 pnpm-workspace.yaml # JSON 值会生成数组 / 对象 pnpm config set --locationproject --json allowBuilds {react: true} # get/list 自 v11 起输出 JSON不再是 INI pnpm config get nodeLinker pnpm config get allowBuilds.react pnpm config list要点get/list输出的都是 JSON 而非旧式 INI--locationproject会把设置写进pnpm-workspace.yaml。七、环境变量pnpm_config_* 取代 npm_config_*pnpm不再读取npm_config_*前缀的环境变量改用pnpm_config_*或PNPM_CONFIG_*pnpm_config_save_exacttrue pnpm add foo对 CI、shell 配置文件、Docker 镜像中残留的npm_config_*迁移到 v11 时必须一并改名为pnpm_config_*。八、改名对照表v10 → v11 必须同步的设置旧设置已移除替代方案说明onlyBuiltDependencies、neverBuiltDependencies、ignoredBuiltDependencies、onlyBuiltDependenciesFileallowBuilds: { name: true\|false }单一映射表统一管理构建脚本审批见 features-supply-chain-security.mdmanagePackageManagerVersions、packageManagerStrict、packageManagerStrictVersion、COREPACK_ENABLE_STRICTpmOnFail: download\|ignore\|warn\|error运行 pnpm 版本与声明版本不一致时的行为useNodeVersiondevEngines.runtime位于package.json运行时版本固定auditConfig.ignoreCvesauditConfig.ignoreGhsas改用 GHSA ID需手动把 CVE-… 转成 GHSA-…allowNonAppliedPatchesallowUnusedPatchesignorePatchFailures已移除补丁失败现在必定抛错package.json#pnpm字段pnpm-workspace.yaml完全不再读取其中allowBuilds与供应链安全强相关pnpm 11 默认不执行依赖的生命周期脚本preinstall/install/postinstall未列入allowBuilds的包会被阻止配合默认strictDepBuilds: true时安装直接以ERR_PNPM_IGNORED_BUILDS非零退出可用pnpm approve-builds交互式、pnpm approve-builds --all、pnpm add --allow-buildpkg等命令审批。AIRI 仓库的 allowBuilds 就是逐个显式审批的完整样例其中simple-git-hooks: false还带注释说明原因。九、包管理器 / 运行时版本固定package.json{ packageManager: pnpm10.0.0, devEngines: { packageManager: { name: pnpm, version: 11.0.0 12.0.0, onFail: download }, runtime: { name: node, version: 22.x, onFail: download } } }区别要点devEngines.packageManager支持版本区间解析后的版本记录在 lockfile 中packageManager只接受精确版本。不想改动 manifest 时可以用设置项pmOnFail/runtimeOnFail覆盖onFail行为。AIRI 根 package.json 即使用packageManager: pnpm11.24.0精确固定版本供 Corepack 等工具自动选用devEngines.runtime则可在团队内统一 Node 主版本并在 CI 与本地通过pnpm install --no-runtime跳过自动安装。十、从旧版迁移的一键路径如果仓库仍在 pnpm 10 或更早的配置习惯上官方推荐的机械迁移方式是一条 codemod详见 best-practices-migration.mdcd /path/to/project pnpx codemod run pnpm-v10-to-v11它自动完成把package.json#pnpm设置搬进pnpm-workspace.yaml拆分.npmrc仅保留认证 / registry其余转为 camelCase 键把四个 build 审批设置合并为allowBuilds用pmOnFail替代packageManagerStrict*重命名allowNonAppliedPatches→allowUnusedPatches、auditConfig.ignoreCves→auditConfig.ignoreGhsas把useNodeVersion转为devEngines.runtime并升级packageManager。无法自动完成、需要人工跟进的点包括CVE→GHSA 改写、处理ignorePatchFailures移除后的补丁失败、npm_config_*改名、以及pnpm link只接受路径、pnpm add -g .注册全局 bin 等 CLI 行为变化。十一、核心要点速记所有 pnpm 设置进pnpm-workspace.yamlcamelCase或全局config.yaml.npmrc只负责认证 / registry。package.json#pnpm与npm_config_*环境变量不再被读取。工作区内包级设置使用根目录的packageConfigs。构建脚本审批收敛为一张allowBuilds映射表包管理器严格性收敛为pmOnFail一个设置。pnpm config get/list输出 JSON--locationproject写入pnpm-workspace.yaml。AIRI 仓库的 pnpm-workspace.yaml、package.json 与 patches 目录是这套 pnpm 11 配置模型在超大型 monorepo 上的完整落地样本配套的 pnpm 技能体系入口见 .agents/skills/pnpm/SKILL.md还覆盖了 CLI、workspaces、catalogs、overrides、patches、供应链安全等主题可继续深入阅读。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐pnpm 配置完全指南pnpm-workspace.yaml、全局 config.yaml 与 .npmrc 的职责划分pnpm 配置完全指南pnpm workspace.yaml、全局 config.yaml 与 .npmrc 的职责划分 pnpm 的配置体系在 v11/v1AI 技能人工智能AIRI 单仓的 pnpm 实践手册从 pnpm-workspace.yaml 配置模型到 Catalogs、Patches 与供应链安全AIRI 单仓的 pnpm 实践手册从 pnpm workspace.yaml 配置模型到 Catalogs、Patches 与供应链安全 本文以 AIRIAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染airi 仓库 pnpm 迁移实战从 npm/Yarn 到 pnpm再到 v10→v11 配置迁移全解析airi 仓库 pnpm 迁移实战从 npm/Yarn 到 pnpm再到 v10→v11 配置迁移全解析 本篇基于 airi 仓库内置的迁移技能文档 besAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染上一篇【亲测免费】 VueSimpleCalendar——轻量级Vue日历组件的不二之选下一篇Halo主题选择指南100免费主题如何挑安装、自定义与截图预览一步到位创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考