diff --git a/docs/MigrationFrom1x.md b/docs/MigrationFrom1x.md
new file mode 100644
index 000000000..fee78fb47
--- /dev/null
+++ b/docs/MigrationFrom1x.md
@@ -0,0 +1,107 @@
+# Mirai - Migration From 1.x
+
+本文介绍如何从 1.x 升级到 2.x。
+
+根据你的语言选择：[Kotlin](#使用-kotlin) | [Java](#使用-java)
+
+## 使用 Kotlin
+
+### 如何自动完成 Kotlin 的错误替换
+
+仅 IntelliJ IDEA 和 Android Studio 支持这个功能。
+
+把光标放在一个错误中间（或者按 F2 自动跳转到错误），使用 `Alt + Enter` 快捷键，会得到弹窗如下图。
+
+![YBP47V_Z640J_YU5WZ_JVPW.png](https://i.loli.net/2020/12/18/CiX9qApu5BnVPch.png)
+
+第一项为仅替换这一个错误，第二项为替换项目中的所有这个错误。一般推荐选择第二项并回车即可。
+
+**Mirai 的修改都尽可能地提供了这样的替换，请依次按如下步骤更新以下几个版本，才能使用这些替换。**  
+部分无法提供自动替换的修改会在下文说明。
+
+### `1.x` -> `2.0-M1-1`
+
+替换依赖（可以直接全局搜索替换）:
+- `net.mamoe:mirai-core` -> `net.mamoe:mirai-core-api`
+- `net.mamoe:mirai-core-qqandroid` -> `net.mamoe:mirai-core`
+
+**Kotlin**:
+
+1. 将 `MessageChain[Image]` 等 IDE 会提示错误的调用调整为:
+   - `.findIsInstance<Image>()` （`Image` 不存在时返回 `null`）
+   - `.firstIsInstance<Image>()`  （`Image` 不存在时抛出异常）
+
+   **提示**: 如果你是想获取消息的内容，可以使用 `messageChain.content` 扩展，而不需要使用 `MessageChain[PlainText]`
+
+2. `Bot.getFriend` 等函数在找不到好友时会抛出异常，现在它们会返回 `null`。  
+   请替换 `Bot.getFriend` 为 `Bot.getFriendOrFail`。
+
+
+只要能通过编译就可以适配下一个版本。
+
+### `2.0-M1` -> `2.0-M2`
+
+修改都可以自动替换完成。**但请不要跳过 `2.0-M2` 这一步骤。**
+
+### `2.0-M2` -> `2.0-RC`
+
+1. 戳一戳事件由以前的多个事件变为了统一的单个 `NudgeEvent`。若有使用请直接参考 `NudgeEvent` 源码修改。
+
+2. `Listener.ConcurrencyKind` 和 `Listener.EventPriority` 由嵌套类移动到顶层，请执行全局替换：
+   - `Listener.ConcurrencyKind` -> `ConcurrencyKind`
+   - `Listener.EventPriority` -> `EventPriority`
+
+3. `IMirai` 低级 API 函数名现在不再带有 `_lowLevel` 前缀, 直接删除前缀即可。
+
+
+其他修改都可以自动替换完成。
+
+
+### `2.0-RC` -> `2.0.0`
+
+本文编写时 `2.0.0` 还未发布。如果你阅读时已经发布了，请更新到 `2.0.0`。不需要额外迁移。
+
+至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+
+## 使用 Java
+
+**请依次按如下步骤更新以下几个版本**
+
+### `1.x` -> `2.0-M1`
+
+- 消息事件包名有调整, 请根据 IDE 提示自动导入引用失效的包.
+- Bot 构造方法调整, 将原 `BotFactoryKt.newBot(...)` 替换为 `BotFactory.INSTANCE.newBot(...)`
+- 如果有调用 `Utils.getDefaultLogger().invoke(...)`，替换为 `MiraiLogger.create(...)`
+- `Bot.getFriend` 等函数在找不到好友时会抛出异常，现在它们会返回 `null`。  
+  请替换为 `Bot.getFriendOrFail`。
+
+### `2.0-M1` -> `2.0-M2`
+
+图片和语音上传的 API 有更改。
+
+新增了资源 API，可以统一缓存文件。
+```
+ExternalResource.create(file);
+ExternalResource.create(inputStream);
+```
+
+上传一个资源为图片或语音：
+```
+contact.uploadImage(resource);
+contact.uploadVoice(resource);
+```
+
+或者使用工具方法直接发送一个 `File` 或 `InputStream` 为图片：
+```
+Contact.sendImage(contact, inputStream); // 返回 MessageReceipt
+Contact.sendImage(contact, file);        // 返回 MessageReceipt
+
+Contact.uploadImage(contact, inputStream); // 返回 Image 消息
+Contact.uploadImage(contact, file);        // 返回 Image 消息
+```
+
+### `2.0-M2` -> `2.0-RC` (`2.0.0`)
+
+如果 `2.0.0` 已经发布，请更新到 `2.0.0` 而不需要更新到 `2.0-RC`。
+
+这个版本的修改基本不影响 Java 使用。至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)