深入理解UmiJS/Dumi项目目录结构设计

深入理解UmiJS/Dumi项目目录结构设计

dumi Static Site Generator for component library development 项目地址: https://gitcode.com/gh_mirrors/du/dumi

前言

UmiJS/Dumi作为一款专注于组件开发及文档生成的工具，其项目结构设计体现了"约定优于配置"的理念。本文将全面解析Dumi项目的标准目录结构，帮助开发者快速掌握项目组织规范。

基础目录结构解析

通过官方脚手架创建的Dumi项目通常包含以下核心目录和文件：

项目根目录/
├── docs/             # 组件库文档目录
│   ├── index.md      # 文档首页
│   └── guide.md      # 其他文档页面
├── src/              # 组件库源码目录
│   ├── Foo/          # 单个组件目录
│   │   ├── index.tsx # 组件实现
│   │   └── index.md  # 组件文档
│   └── index.ts      # 组件库入口
├── .dumirc.ts        # Dumi配置文件
└── .fatherrc.ts      # 组件打包配置

文档目录(docs/)

docs目录用于存放项目的说明文档，采用Markdown格式编写。Dumi会自动将这些文档转换为可访问的网页，并生成对应的路由。

源码目录(src/)

src目录是组件开发的核心区域，采用"组件即目录"的组织方式：

1. 每个组件拥有独立目录
2. 组件实现与文档共存
3. 通过index.ts统一导出

这种结构既保持了代码的模块化，又实现了文档与代码的紧密关联。

特殊约定目录(.dumi/)

Dumi在.dumi目录下定义了一系列特殊约定，这些约定仅影响文档站点，不会干扰组件库本身的构建。

全局样式管理

Dumi提供了两种全局样式引入方式：

1. global.(less|sass|scss|css)：添加全新样式规则
2. overrides.(less|sass|scss|css)：覆盖现有样式（自动提升优先级）

/* .dumi/overrides.css示例 */
/* 覆盖默认主题颜色 */
:root {
  --c-primary: #1890ff;
}

全局脚本注入

通过global.(js|jsx|ts|tsx)文件，可以在文档站点全局注入JavaScript逻辑，常用于：

• 错误监控
• 性能统计
• 全局事件处理

运行时配置

app.(js|jsx|ts|tsx)文件允许开发者修改Dumi的运行时行为，例如：

• 自定义路由
• 修改渲染逻辑
• 扩展运行时能力

加载状态组件

在大型文档站点中，异步加载是常见场景。loading.(js|jsx|ts|tsx)组件让开发者可以自定义页面切换时的加载动画，提升用户体验。

自定义404页面

通过.dumi/pages/404.(js|jsx|ts|tsx)可以创建个性化的404页面，建议包含：

• 友好的错误提示
• 主要导航链接
• 搜索功能（如有）

最佳实践建议

1. 组件文档化：坚持为每个组件编写配套的Markdown文档，保持文档与代码同步更新

2. 样式管理：

   • 使用CSS Modules避免样式冲突
   • 全局样式尽量通过.dumi目录管理

3. 类型安全：

   • 为TypeScript项目添加类型定义
   • 导出组件Props类型

4. 构建优化：

   • 合理配置.fatherrc.ts实现按需加载
   • 注意组件之间的依赖关系

常见问题解答

Q: 为什么我的全局样式没有生效？ A: 请检查文件是否放在.dumi目录下，且使用了正确的文件名和后缀。

Q: 如何组织大型组件库的目录结构？ A: 建议按功能或业务域划分子目录，保持扁平化结构，避免嵌套过深。

Q: 静态站点和组件库项目的区别？ A: 静态站点项目通常不需要src目录，主要关注docs目录的内容组织。

通过理解Dumi的目录结构设计，开发者可以更高效地组织项目代码，充分发挥Dumi在组件开发和文档生成方面的优势。

dumi Static Site Generator for component library development 项目地址: https://gitcode.com/gh_mirrors/du/dumi