子路径模式指通过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 包
