从 dumi 1.x 升级

参考该文档可将 dumi 1.x 项目升级到 dumi 2.0，如果你的项目是从 dumi 1.x 早期的组件研发脚手架初始化，建议同时将项目中的 father-build 升级到 father 4，以获得更好的组件源码构建体验。

环境检查

dumi 2.0 最低支持 Node.js v14 版本，升级前请确保设备安装的 Node.js 版本是 14+。

项目模板升级

方案一：重新初始化

倘若在 dumi 1.x 初始化模板的基础上改动不大，建议使用 create-dumi 重新初始化一套模板，将源码及文档拷贝进去、再做适当调整验证。

确保以下操作是在 git 仓库中进行，且工作区是干净的：

$ git rm -rf ./*        # 清空现有仓库文件（仅工作区清空，文件仍受 Git 版本控制）
$ npx create-dumi       # 然后选择需要的模板
$ rm -rf docs src       # 删除初始化模板的 docs 及 src
$ git checkout src docs # 恢复原有的源码及文档

至此模板升级完成，可进行后续的文档及配置升级。

方案二：手动升级

倘若在 dumi 1.x 初始化模板的基础上改动较大，建议手动升级做最小化调整，步骤如下：

更新 package.json

{
  "scripts": {
+   "prepare": "dumi setup"
  },
  "devDependencies": {
-   "dumi": "^1.0.0",
+   "dumi": "^2.0.0"
  }
}

更新 tsconfig.json

{
  "compilerOptions": {
    "paths": {
+     "@@/*": [".dumi/tmp/*"]
    }
  }
}

更新 .gitignore

- .umi
- .umi-test
- .umi-production
+ .dumi/tmp
+ .dumi/tmp-test
+ .dumi/tmp-production

更新外部引入 demo

单标签改为双标签。

- <code src="path/to/demo.tsx" />
+ <code src="path/to/demo.tsx"></code>

项目文件升级

dumi 2.0 将使用特有的 .dumirc.ts 作为配置文件，请将原有的 .umirc.ts 或者 config/config.ts 重命名为 .dumirc.ts，并做如下调整：

+ import { defineConfig } from 'dumi';

- export default {
+ export default defineConfig({
   # 以下为文档配置升级
   # 已内置全文搜索，默认不再集成 algolia，有需要可以手动覆盖 SearchBar 组件
-  algolia: { ... },
   # 由于 doc 模式已废弃，所以该配置项也一并废弃
-  mode: 'doc',
   # dumi 1.x 用 title 作为组件库名称，如果你希望设置的是组件库名称而非页面标题，请改用 name
-  title: 'xxx',
+  themeConfig: { name: 'xxx' },
   # logo 配置项升级
-  logo: 'xxx',
+  themeConfig: { logo: 'xxx' },
   # menus 升级为 themeConfig.sidebar
-  menus: [...],
+  themeConfig: {
+    sidebar: {
+      '/guide': {
+        title: '分组名称（可选）',
+        children: [{ title: '标题', link: '链接' }],
+      },
+    },
+  },
   # navs 升级为 themeConfig.nav
-  navs: [...],
+  themeConfig: {
+    nav: [{ title: '标题', link: '链接' }],
+  },
   # locales 配置格式升级
-  locales: [['zh-CN', '中文']],
+  locales: [{ id: 'zh-CN', name: '中文' }], // 2.0 默认值
   # resolve 配置项升级
   resolve: {
     # 拆分普通文档解析（多层）和资产文档（单层 + 按分类添加路由前缀）解析，可访问约定式路由了解更多
-    includes: ['docs', 'src'],
+    docDirs: ['docs'], // 2.0 默认值
+    atomDirs: [{ type: 'component', dir: 'src' }], // 2.0 默认值
     # passive 配置项升级，用 codeBlockMode 替代
-    passivePreview: true,
+    codeBlockMode: 'passive',
     # 废弃，由注册的技术栈决定解析什么语言的 demo
-    previewLangs: [...],
   },
   sitemap: {
-    excludes: [...],
     # sitemap.excludes 配置项升级
+    exclude: [...],
   },
   # apiParser 的子配置项暂不支持，后续版本会支持
   apiParser: {
-    ...
   },
   # 以下为基础配置升级
   # favicon 配置项升级
-  favicon: 'xxx',
+  favicons: ['xxx'],
   # 已废弃，默认开启动态加载
-  dynamicImport: {},
   # 默认开启
-  fastRefresh: {},
   # 默认使用 webpack 5
-  webpack5: {},
});

Monorepo 模式下特别注意 🚨：

由于 dumi 2 不再感知 monorepo ，因此会出现热更新失效的问题，需要手动配置包名到 src 的 alias。

alias: {
  pkg: path.join(__dirname, 'packages/pkg/src');
}

目录结构升级

由于 dumi 2.0 拆分了普通文档与资产文档的解析逻辑，其中资产文档的解析仅识别解析路径顶层 md 及顶层下的 index.md，所以在 src 下的文档目录结构可能需要做调整，例如：

.
└── src
    ├── Foo
    │   ├── index.md     # ✅ 识别
    │   └── a.md         # ❗️ 非 index.md 不再识别
    ├── components
    │   └── Bar
    │       └── index.md # ❗️ 嵌套层级不再识别
    └── Hello.md         # ✅ 识别

如果不方便调整结构，可以通过配置 resolve.atomDirs 来指定识别的目录，例如：

export default {
  resolve: {
    atomDirs: [
      { type: 'component', dir: 'src' }, // 默认值
      # 追加一个组件资产的解析目录
+     { type: 'component', dir: 'src/components' },
    ]
  }
}

Monorepo 模式下

export default {
  resolve: {
    atomDirs: [
      { type: 'component', dir: 'src' }, // 默认值
      # 做顶级路由的区分，被解析到的 md 均有对应 `type` 复数形式的路由前缀，例如 `/basic-components/foo`
+     { type: 'basic-component', dir: 'packages/basic/src' },
+     { type: 'complex-component', dir: 'packages/complex/src' },
    ]
  }
}

FrontMatter 升级

Markdown 头部支持的 frontmatter 有如下变化：

---
  nav:
    # 不支持配置路径，以文件夹目录结构为准
-   path: /xxxx
  group:
    # 不支持配置路径，group 没有路径的概念了
-   path: /xxxx
  # 已废弃
- legacy: /xxxx
  hero:
    # 新的默认主题不支持展示 hero 图片
-   image: xxxx
    # desc 配置项升级
-   desc: xxxx
+   description: xxxx
  features:
    # 新的默认主题只支持配置 emoji 作为图标
-   - icon: xxxx
+   - emoji: 🚀
    # desc 配置项升级
-     desc: xxxx
+     description: xxxx
  # 请在 .dumirc.ts 的 themeConfig.footer 中配置
- footer: xxx
  # 已废弃
- translateHelp: true
  # hide 配置项升级为 debug
- hide: true
+ debug: true
  # 以下配置暂不支持，后续版本会支持
- sidemenu: false
---

Demo 支持的 frontmatter 有如下变化：

/**
   # desc 配置项升级
-* desc: xxxx
+* description: xxxx
   # 已废弃，可通过覆盖 PreviewerActions 组件实现全局控制
-* hideActions: ['xxx']
 */

至此，可以启动 dev server 验证项目运行情况，如果没什么异常就意味着升级完成了，如果升级过程中碰到任何问题，欢迎到 GitHub 讨论区内反馈。