子路径模式指通过tsconfig的paths+references与composer的path repositories协同实现本地包精准引用：baseurl须设为"./packages"，paths映射严格匹配package name，子包启用composite:true并声明references，php侧repositories路径须精确对应且启用symlink。

子路径模式（Subpath Patterns）本身不是标准术语，但在 Monorepo 场景中，它实际指向的是对 本地包路径引用的结构化控制——核心目标是让模块导入既准确又可维护，避免硬编码相对路径、规避类型/运行时错位，并支撑跨包开发与构建一致性。它不依赖某一个工具自动识别，而是靠 tsconfig 的 paths + references + composer.json 的 path repositories 三者协同对齐来落地。

明确子路径映射规则：统一 baseUrl 和 paths

在根目录 tsconfig.json 中定义全局路径别名，是实现精准引用的第一步。关键不是“写得多”，而是“对得准”：

• baseUrl 必须指向 packages 目录（如 "baseUrl": "./packages"），所有子包路径都以此为基准
• paths 映射需严格对应 package name 字段，例如 @myorg/utils → ["./utils/src"]，不能写成 ["utils/src"] 或 ["../utils/src"]
• 每个子包自己的 tsconfig.json 不再重复配置 paths，而是 继承根配置并启用 composite: true，确保 TypeScript 能识别该包为可构建单元

强制类型与构建联动：用 references 锁定依赖链

仅靠 paths 别名，TypeScript 只能解决编辑器跳转和类型检查，但无法保证构建顺序和输出产物可用。这时必须显式声明引用关系：

• 在依赖方（如 packages/app/tsconfig.json）中加入 "references": [{ "path": "../utils/tsconfig.json" }]
• 被依赖方（packages/utils/tsconfig.json）必须含 "composite": true 和 "outDir"，且 include 覆盖源码范围
• 执行 tsc --build 时，TS 会按 references 拓扑排序编译，生成可复用的 .d.ts 和 .js，避免“类型存在但运行时报错找不到模块”

保障运行时真实可用：Composer path 仓库必须精确匹配

PHP 侧的子路径对齐完全依赖根 composer.json 的 repositories 配置。这里没有通配魔术，只有路径精确性：

• 每个本地包必须单独列在 repositories 下，"type": "path"，"url": "packages/utils" —— 注意是相对根目录的路径，不能带 ./ 或结尾斜杠
• 子包 composer.json 中的 "name"（如 "myorg/utils"）必须与 require 语句中写的完全一致，大小写、斜杠都不能错
• 启用符号链接需加 "options": {"symlink": true}，否则安装后是复制而非链接，改代码不生效
• 每次增删包或改路径后，务必运行 composer clear-cache && composer install，否则 Composer 可能缓存旧路径导致装错

验证是否对齐成功：三个信号缺一不可

真正的“精准对齐”不是配置完就结束，而要通过三重验证：

• TS 编辑器里能 Ctrl+点击跳转到目标包的源码，且无类型报错
• 运行 tsc --build 成功，且 packages/utils/dist 下产出有效类型声明和 JS 文件
• PHP 项目中 new \MyOrg\Utils\Helper() 可正常实例化，composer show myorg/utils 显示来源为 path 链接，非 dist 包