---
url: /docs/adr/006-subpath-imports.md
---
# 决策 006：包内导入约定

**状态：** 已采纳。**日期：** 2026-09-11。

## 问题

原项目混用仅由 TypeScript 配置解释的路径别名和包声明的子路径导入，共享配置可能意外把一个应用的导入解析到另一个应用。

## 决策

`apps/app`、`apps/web` 和 `packages/ui` 的包内导入使用 `#` 前缀，并在各自 `package.json` 的 `imports` 声明。跨共享包使用 `@repo/*`；接口、数据库和直接运行的脚本可使用相对路径。

工作台还在 TypeScript 配置声明对应路径映射，以同时满足编译器和打包器对扩展名的不同处理。修改时保持两处一致，不增加跨应用的全局回退路径。

## 示例

```ts
import { auth } from "#lib/auth";
import { websiteConfig } from "@repo/core";
```

第一条引用当前工作台文件，第二条引用共享包。包内无扩展名的浏览器代码由打包器解析，不能默认直接用原生 Node 运行。

## 取舍

统一约定减少复制组件时解析到错误目录的风险，但工作台有两处映射需要同步。枚举所有扩展名的条件导入会增加目录变更成本，因此不作为默认方案。