TypeScript项目结构设计：lib、src、dist的职责划分

TypeScript项目结构设计lib、src、dist的职责划分在TypeScript项目尤其是库开发、工程化应用开发中lib、src、dist是最核心的目录清晰的职责划分能让项目结构更规范、维护成本更低、发布流程更可控。本文会明确三者的核心职责结合场景说明划分逻辑并给出通用的目录示例。一、核心目录的核心职责1. src项目“源代码”目录核心中的核心定义存放项目所有手写的、未编译的TypeScript源代码是开发阶段的主要工作目录。核心职责包含业务逻辑、组件、工具函数、配置项、类型定义等所有“活代码”遵循模块化组织按功能/业务/领域划分子目录可包含测试文件或单独拆出__tests__/test目录不包含编译产物、第三方依赖、构建配置的输出。适用所有场景无论是应用开发Web/Node.js、库开发src都是必选目录是项目的“源码仓库”。典型子目录结构应用开发src/ ├── api/ # 接口请求封装如Fetch/axios封装 ├── components/ # 通用组件React/Vue组件等 ├── hooks/ # 自定义钩子如React Hooks ├── utils/ # 工具函数如日期处理、数据校验 ├── types/ # 全局类型定义如接口、枚举、类型别名 ├── config/ # 业务配置如环境变量、常量 ├── App.tsx # 根组件/入口逻辑 └── main.ts # 应用入口文件典型子目录结构库开发src/ ├── core/ # 库的核心逻辑如核心算法、主类 ├── plugins/ # 扩展插件 ├── utils/ # 库内工具函数 ├── types/ # 库对外暴露的类型 ├── index.ts # 库的入口导出所有公开API └── entry.ts # 可选多入口时的子入口2. dist编译/构建“产物”目录输出目录定义存放项目经tscTypeScript编译器或构建工具Vite/Webpack/Rollup处理后的产物是最终运行/发布的目录。核心职责包含编译后的JavaScript文件.js、类型声明文件.d.ts、sourcemap文件.map产物需符合发布/运行要求如ESModule/CJS模块化、压缩/未压缩版本、按需加载拆分目录结构通常和src有映射关系保持模块导入路径一致属于“临时/生成目录”可被.gitignore忽略构建时自动清空/重新生成。关键特性应用开发dist是部署到服务器/打包后的前端资源如index.html、assets、main.js库开发dist是发布到npm的最终目录包含可被其他项目导入的JS类型文件。典型dist目录结构库开发dist/ ├── es/ # ESModule版本供浏览器/ESM项目使用 │ ├── core/ │ ├── utils/ │ ├── index.js │ └── index.d.ts ├── cjs/ # CommonJS版本供Node.js项目使用 │ ├── core/ │ ├── utils/ │ ├── index.js │ └── index.d.ts ├── umd/ # UMD版本供CDN/非模块化环境使用 │ ├── lib.umd.js │ └── lib.umd.min.js └── types/ # 统一的类型声明可选或分散在es/cjs中 └── index.d.ts3. lib第三方依赖/内部公共库目录可选易混淆定义lib是容易被误用的目录核心是存放“非当前项目源码、但需直接引用的代码”不是所有项目都需要。核心职责分场景场景1库开发最常用存放项目依赖的“内部公共库”或“修改后的第三方库源码”区别于node_modules的黑盒依赖例如项目依赖团队内部未发布到npm的基础库可将其源码放在lib例如需要修改第三方库的部分逻辑将源码拷贝到lib并定制化。场景2应用开发极少用几乎不用lib而是通过node_modules管理第三方依赖仅当需要“脱离npm管理、直接引用源码”时使用如老项目依赖的未打包脚本。场景3TypeScript编译器的“lib”配置易混淆点注意tsconfig.json中的compilerOptions.lib如[ES2020, DOM]是指定TS编译时要包含的“内置库类型”如DOM API、ES6特性和项目目录中的lib无关不要混淆。典型lib目录结构库开发lib/ ├── shared-utils/ # 团队内部公共工具库未发布到npm │ ├── index.ts │ └── types.ts └── modified-lodash/ # 定制化的lodash子集修改了部分方法 └── index.js二、关键划分原则避免踩坑1. 源码与产物严格分离src只放手写源码开发者只修改这里dist只放构建产物禁止手动修改构建脚本如vite.config.ts/webpack.config.js需确保dist在构建前清空如用rimraf dist避免旧产物残留。2. lib目录的“最小使用原则”优先用node_modules管理第三方依赖仅当无法通过npm/yarn管理时如内部未发布库、定制化第三方源码才用liblib内的代码尽量保持独立避免和src代码深度耦合便于后续迁移到npm管理。3. 类型文件的归属项目内的类型定义放在src/types属于源码随src编译到dist第三方库的类型声明优先用types/xxxnpm包若没有则放在lib/types发布到npm的库需确保dist中包含完整的.d.ts文件通过tsconfig.json的declaration: true生成。三、完整项目目录示例库开发结合三者的职责给出一个TypeScript库开发的通用目录结构my-ts-lib/ ├── src/ # 核心源码 │ ├── core/ # 库核心逻辑 │ │ ├── index.ts │ │ └── utils.ts │ ├── plugins/ # 扩展插件 │ │ └── auth.ts │ ├── types/ # 类型定义 │ │ └── index.ts │ └── index.ts # 库入口导出所有公开API ├── lib/ # 内部依赖库 │ └── team-common/ # 团队内部公共库 │ └── index.ts ├── dist/ # 构建产物git忽略 │ ├── es/ # ESM版本 │ ├── cjs/ # CJS版本 │ └── types/ # 类型声明 ├── tsconfig.json # TS编译配置 ├── rollup.config.ts # 构建配置库开发常用Rollup ├── package.json └── .gitignore # 忽略dist、node_modules等四、tsconfig.json的配套配置关键目录划分需要TS配置配合确保源码编译、产物输出符合预期{compilerOptions:{rootDir:./src,# 指定源码根目录仅编译src下的代码outDir:./dist/cjs,#CJS产物输出到dist/cjsdeclaration:true,# 生成.d.ts类型文件declarationDir:./dist/types,# 类型文件统一输出到dist/typeslib:[ES2020,DOM],#TS编译时的内置库类型和项目lib目录无关module:CommonJS,# 模块系统可通过多配置输出ESM/CJStarget:ES2018,# 目标JS版本sourceMap:true,# 生成sourcemap便于调试paths:{# 路径映射简化导入/*:[src/*],lib/*:[lib/*]# 映射lib目录的导入路径}},include:[src/**/*,lib/**/*],# 编译src和lib下的TS代码exclude:[node_modules,dist]# 排除产物和第三方依赖}五、常见误区纠正误区1把lib当作src的子目录错误src/lib/xxx混淆源码和外部依赖正确lib和src同级仅存放非当前项目的源码依赖。误区2手动修改dist目录的文件错误为了临时修复问题直接改dist中的JS文件正确修改src中的源码重新构建生成dist否则下次构建会覆盖手动修改的内容。误区3所有项目都建lib目录错误应用开发中盲目建lib把第三方依赖如lodash拷贝进去正确应用开发优先用node_modules仅当必须脱离npm管理时才用lib。六、总结目录核心职责是否必选操作方式src手写TypeScript源码项目核心逻辑是开发者日常修改、维护dist构建/编译产物最终运行/发布的代码是构建工具自动生成禁止手动修改lib非npm管理的内部/定制化依赖否仅在无法通过npm管理时使用清晰的目录职责划分本质是“分离关注点”开发者只关注src的源码开发构建工具负责生成dist的产物lib仅作为特殊依赖的补充。这种结构不仅符合工程化最佳实践也能让团队协作更高效新人能快速定位代码位置。