docs: 文档更新

McGorger · Dec 2, 2021 · 9035858 · 9035858
1 parent 3859e59
commit 9035858
Show file tree

Hide file tree

Showing 16 changed files with 142 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -142,7 +142,13 @@ For more commands, see [DEVELP](https://github.com/micro-zoe/micro-app/blob/mast
 <details>
   <summary>Does it support vite?</summary>
 
-  Yes, please see [adapt vite](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/advanced?id=_2%e3%80%81%e9%80%82%e9%85%8dvite) for details.
+  Yes, please see [adapt vite](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/vite) for details.
+</details>
+
+<details>
+  <summary>Does it support ssr?</summary>
+
+  Yes, please see [nextjs](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/nextjs), [nuxtjs](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/nuxtjs) for details.
 </details>
 
 # Contributors

diff --git a/README.zh-cn.md b/README.zh-cn.md
@@ -143,7 +143,13 @@ yarn start # 访问 http://localhost:3000
 <details>
   <summary>支持vite吗?</summary>
 
-  支持，详情请查看[适配vite](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/advanced?id=_2%e3%80%81%e9%80%82%e9%85%8dvite)
+  支持，详情请查看[适配vite](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/vite)
+</details>
+
+<details>
+  <summary>支持ssr吗?</summary>
+
+  支持，详情请查看[nextjs](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/nextjs)、[nuxtjs](https://micro-zoe.github.io/micro-app/docs.html#/zh-cn/framework/nuxtjs)
 </details>
 
 # 贡献者们

diff --git a/docs/sidebar.md b/docs/sidebar.md
@@ -18,7 +18,7 @@
   - [API](zh-cn/api)
   - [路由](zh-cn/route)
   - [应用之间跳转](zh-cn/jump)
-  - [部署](zh-cn/deploy)
+  <!-- - [部署](zh-cn/deploy) -->
 
 - 手把手
   - [说明](zh-cn/framework/introduce)

diff --git a/docs/zh-cn/advanced.md b/docs/zh-cn/advanced.md
@@ -46,7 +46,7 @@ microApp.start({
 
 **我的项目是否需要切换为umd模式?**
 
-如果你不希望子应用做过多修改，或子应用渲染和卸载不频繁，那么使用默认模式即可，如果子应用渲染和卸载非常频繁建议使用umd模式。
+如果子应用渲染和卸载不频繁，那么使用默认模式即可，如果子应用渲染和卸载非常频繁建议使用umd模式。
 
 **切换为umd模式：子应用在window上注册mount和unmount方法**
 
@@ -283,8 +283,10 @@ if (window.__MICRO_APP_ENVIRONMENT__) {
 
 > [!NOTE]
 >
-> 1、nextjs, nuxtjs等ssr框架作为子应用时暂不支持umd模式
+> 1、mount和unmount方法都是必须的
 >
-> 2、因为注册了`unmount`函数，所以卸载监听事件 `window.addEventListener('unmount', () => {})` 就不需要了
+> 2、nextjs, nuxtjs等ssr框架作为子应用时暂不支持umd模式
 >
-> 3、umd模式下，因为初次渲染和后续渲染逻辑不同，可能会出现一些问题，如：[#138](https://github.com/micro-zoe/micro-app/issues/138)
+> 3、因为注册了`unmount`函数，所以卸载监听事件 `window.addEventListener('unmount', () => {})` 就不需要了
+>
+> 4、umd模式下，因为初次渲染和后续渲染逻辑不同，可能会出现一些问题，如：[#138](https://github.com/micro-zoe/micro-app/issues/138)
diff --git a/docs/zh-cn/api.md b/docs/zh-cn/api.md
@@ -33,6 +33,8 @@ preFetch(() => [
 ## 2、getActiveApps
 **描述：获取正在运行的子应用，不包含已卸载和预加载的应用**
 
+**版本限制：** 0.5.2及以上版本
+
 **介绍：**
 ```js
 function getActiveApps(): string[]
@@ -48,6 +50,8 @@ getActiveApps() // [子应用name, 子应用name, ...]
 ## 3、getAllApps
 **描述：获取所有子应用，包含已卸载和预加载的应用**
 
+**版本限制：** 0.5.2及以上版本
+
 **介绍：**
 ```js
 function getAllApps(): string[]
@@ -61,6 +65,7 @@ getAllApps() // [子应用name, 子应用name, ...]
 ```
 
 
+
 ## 4、version
 **描述：查看版本号**
 

diff --git a/docs/zh-cn/changelog.md b/docs/zh-cn/changelog.md
@@ -12,6 +12,10 @@
 
 `2021-12-02`
 
+- **New**
+
+  - 🆕 新增了对ssr模式的全局配置的支持。
+
 - **Bug Fix**
 
   - 🐞 修复了沙箱中注册的全局变量的映射key在部分场景下没有及时删除的问题。

diff --git a/docs/zh-cn/deploy.md b/docs/zh-cn/deploy.md
@@ -1 +1,87 @@
-deploy
+
+## 前言
+我们强烈建议你保持开发环境和线上环境路径(*即webpack的publicPath*)的一致性，以避免在部署后出现问题，无论是基座应用还是子应用。
+
+比如一个应用，在部署时作为文件夹 `my-app` 放入服务器根目录，那么配置如下：
+<!-- tabs:start -->
+#### ** webpack **
+
+```js
+// webpack.config.js
+module.exports = {
+  output: {
+    path: 'my-app',
+    publicPath: process.env.NODE_ENV === 'production' ? '/my-app/' : '', // bad ❌
+    publicPath: '/my-app/', // good 👍
+  }
+}
+```
+
+#### ** vue-cli **
+```js
+// vue.config.js
+module.exports = {
+  outputDir: 'my-app',
+  publicPath: process.env.NODE_ENV === 'production' ? '/my-app/' : '', // bad ❌
+  publicPath: '/my-app/', // good 👍
+}
+```
+<!-- tabs:end -->
+
+## 开始
+正常来说只要开发环境和线上环境资源路径一致，并在部署后设置好nginx的跨域支持，就不会出现问题，在开发环境能够正常运行的项目，部署到服务器也一定可以正常运行。
+
+但在实际开发中经常会出现地址404、资源丢失等问题，这通常是因为服务器配置错误或者micro-app元素url属性地址错误导致。
+
+我们以[micro-app-demo](https://github.com/micro-zoe/micro-app-demo)为例介绍部署相关内容，以供大家参考，因为`micro-app-demo`覆盖了history路由、hash路由、ssr、根路径、二级路径等大部分场景，是一个典型的案例。
+
+**仓库代码的目录结构：**
+```
+.
+├── child_apps
+│   ├── angular11        // 子应用 angular11 (history路由)
+│   ├── nextjs11         // 子应用 nextjs11 (history路由)
+│   ├── nuxtjs2          // 子应用 nuxtjs2 (history路由) 
+│   ├── react16          // 子应用 react16 (history路由)
+│   ├── react17          // 子应用 react17 (hash路由)
+│   ├── sidebar          // 子应用 sidebar，公共侧边栏
+│   ├── vite-vue3        // 子应用 vite (hash路由)
+│   ├── vue2             // 子应用 vue2 (history路由)
+│   └── vue3             // 子应用 vue3 (history路由)
+├── main_apps
+│   ├── angular11        // 主应用 angular11 (history路由)
+│   ├── nextjs11         // 主应用 nextjs11 (history路由)
+│   ├── nuxtjs2          // 主应用 nuxtjs2 (history路由)
+│   ├── react16          // 主应用 react16 (history路由)
+│   ├── react17          // 主应用 react17 (history路由)
+│   ├── vite-vue3        // 主应用 vite (history路由)
+│   ├── vue2             // 主应用 vue2 (history路由)
+│   └── vue3             // 主应用 vue3 (history路由)
+├── package.json
+└── yarn.lock
+```
+
+**部署到服务器的目录结构：**
+
+```
+root(服务器根目录)
+├── child
+│   ├── angular11         // 子应用 angular11
+│   ├── react16           // 子应用 react16
+│   ├── react17           // 子应用 react17
+│   ├── sidebar           // 子应用 sidebar
+│   ├── vite              // 子应用 vite
+│   ├── vue2              // 子应用 vue2
+│   ├── vue3              // 子应用 vue3
+│   ├── nextjs11          // 子应用 nextjs11，为每个基座应用单独打包，端口号：5001~5009
+│   └── nuxtjs2           // 子应用 nuxtjs2，为每个基座应用单独打包，端口号：6001~6009
+│ 
+├── main-angular11        // 主应用 angular11
+├── main-react16          // 主应用 react16
+├── main-react17          // 主应用 react17
+├── main-vite             // 主应用 vite
+├── main-vue2             // 主应用 vue2
+├── main-vue3             // 主应用 vue3
+├── main-nextjs11         // 主应用 nextjs11，监听端口号：5000
+├── main-nuxtjs2          // 主应用 nuxtjs2，监听端口号：7000
+```
diff --git a/docs/zh-cn/framework/angular.md b/docs/zh-cn/framework/angular.md
@@ -1,4 +1,4 @@
-本篇以`angular11`作为案例介绍angular的接入方式，其它版本angular接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
+本篇以`angular 11`作为案例介绍angular的接入方式，其它版本angular接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
 
 ## 作为基座应用
 我们强烈建议基座应用采用history模式，hash路由的基座应用只能加载hash路由的子应用，history模式的基座应用对这两种子应用都支持。

diff --git a/docs/zh-cn/framework/introduce.md b/docs/zh-cn/framework/introduce.md
@@ -15,4 +15,4 @@
 > [!TIP]
 > 以上框架可以任意组合，换句话说任何一个框架都可以作为基座嵌入其它类型的子应用，任何一个框架也可以作为子应用被其它框架嵌入，包括上面没有列举出的其它库，如 svelte、umi ...
 >
-> 我们只举例了部分框架，如果有其它框架需求，请在github上提issue告知我们。
+> 我们只列举了部分框架，如果有其它框架需求，请在github上提issue告知我们。
diff --git a/docs/zh-cn/framework/nextjs.md b/docs/zh-cn/framework/nextjs.md
@@ -1,4 +1,4 @@
-本篇以`nextjs11`作为案例介绍nextjs的接入方式，其它版本nextjs接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
+本篇以`nextjs 11`作为案例介绍nextjs的接入方式，其它版本nextjs接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
 
 ## 作为基座应用
 
@@ -22,7 +22,7 @@ function MyApp({ Component, pageProps }) {
 
     /**
      * BUG FIX
-     * 在nextjs11下，子应用内部跳转，基座无法监听，导致点击浏览器前进、后退按钮，无法回退到正确的子应用页面
+     * 在nextjs 11下，子应用内部跳转，基座无法监听，导致点击浏览器前进、后退按钮，无法回退到正确的子应用页面
      * 通过监听popstate事件，在地址变化时重新替换为next路由来解决这个问题
      */
     window.addEventListener('popstate', () => {
@@ -202,7 +202,7 @@ window.addEventListener('unmount', function () {
 
 **解决方式：**
 
-在部分nextjs版本中(如：nextjs11)，使用`next/image`组件无法正确引入图片，此时推荐使用img元素代替。
+在部分nextjs版本中(如：nextjs 11)，使用`next/image`组件无法正确引入图片，此时推荐使用img元素代替。
 
 #### 2、无法预加载ssr子应用
 
@@ -235,3 +235,8 @@ module.exports = {
   },
 }
 ```
+
+
+> [!TIP]
+>
+> nextjs相关问题可以在[nextjs专属讨论贴](https://github.com/micro-zoe/micro-app/issues/168)下反馈。
diff --git a/docs/zh-cn/framework/nuxtjs.md b/docs/zh-cn/framework/nuxtjs.md
@@ -1,4 +1,4 @@
-本篇以`nuxtjs2`作为案例介绍nuxtjs的接入方式，其它版本nuxtjs接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
+本篇以`nuxtjs 2`作为案例介绍nuxtjs的接入方式，其它版本nuxtjs接入方式会在后续补充，如果你在使用时出现问题，请在github上提issue告知我们。
 
 ## 作为基座应用
 
@@ -222,3 +222,8 @@ module.exports = {
   },
 }
 ```
+
+
+> [!TIP]
+>
+> nuxtjs相关问题可以在[nuxtjs专属讨论贴](https://github.com/micro-zoe/micro-app/issues/169)下反馈。
diff --git a/docs/zh-cn/framework/react.md b/docs/zh-cn/framework/react.md
@@ -1,4 +1,4 @@
-本篇以react16、17作为案例介绍react的接入方式，其它版本react的接入方式以此类推。我们默认开发者掌握了各版本react的开发技巧，如示例中useEffect，在不支持hooks的版本中转换为componentDidMount。
+本篇以`React 16、17`作为案例介绍react的接入方式，其它版本react的接入方式以此类推。我们默认开发者掌握了各版本react的开发技巧，如示例中useEffect，在不支持hooks的版本中转换为componentDidMount。
 
 ## 作为基座应用
 我们强烈建议基座应用采用history模式，hash路由的基座应用只能加载hash路由的子应用，history模式的基座应用对这两种子应用都支持。

diff --git a/docs/zh-cn/framework/vite.md b/docs/zh-cn/framework/vite.md
@@ -1,4 +1,4 @@
-本篇介绍了vite2的接入方式，vite1暂不支持。
+本篇介绍了`vite 2`的接入方式，vite1暂不支持。
 
 ## 作为基座应用
 vite作为基座应用时没有特殊之处，具体方式参考各框架接入文档。

diff --git a/docs/zh-cn/framework/vue.md b/docs/zh-cn/framework/vue.md
@@ -1,4 +1,4 @@
-本篇以vue2、3作为案例介绍vue的接入方式，其它版本vue的接入方式以此类推，我们默认开发者掌握了各版本vue的开发技巧，比如示例中vue2的代码如何转换为vue1。
+本篇以`Vue 2、3`作为案例介绍vue的接入方式，其它版本vue的接入方式以此类推，我们默认开发者掌握了各版本vue的开发技巧，比如示例中vue2的代码如何转换为vue1。
 
 ## 作为基座应用
 我们强烈建议基座应用采用history模式，hash路由的基座应用只能加载hash路由的子应用，history模式的基座应用对这两种子应用都支持。
@@ -265,7 +265,7 @@ export default defineConfig({
 
 #### 3、当基座和子应用都是vue-router4，点击浏览器返回按钮页面丢失
 
-**原因：**vue-router4没有对路由堆栈state做唯一性标记，导致基座和子应用相互影响，vue-router3及其它框架没有类似问题。
+**原因：**vue-router4没有对路由堆栈state做唯一性标记，导致基座和子应用相互影响，vue-router3及其它框架路由没有类似问题。
 
 **测试版本：**[email protected]
 

diff --git a/docs/zh-cn/questions.md b/docs/zh-cn/questions.md
@@ -102,16 +102,13 @@ vue3中需要配置publicPath补全资源路径，详情请查看[publicPath](/z
 
 如果你使用的是`ant-design`等组件库，一般会提供添加前缀进行样式隔离的功能。
 
-## 11、支持vite吗
-支持，详情请查看[适配vite](/zh-cn/advanced?id=_2、适配vite)
-
-## 12、子应用在沙箱环境中如何获取到外部真实window？
+## 11、子应用在沙箱环境中如何获取到外部真实window？
   目前有3种方式在子应用中获取外部真实window
   - 1、new Function("return window")() 或 Function("return window")()
   - 2、(0, eval)('window')
   - 3、window.rawWindow
 
-## 13、错误信息：xxx 未定义
+## 12、错误信息：xxx 未定义
 
 **包括：**
 - `xxx is not defined`
@@ -152,7 +149,7 @@ microApp.start({
 })
 ```
 
-## 14、子应用加载sockjs-node失败
+## 13、子应用加载sockjs-node失败
   这个问题常见于create-react-app创建的子应用，推荐通过插件系统来解决。
 ```js
 microApp.start({
@@ -173,7 +170,7 @@ microApp.start({
 实际情况可能更加复杂，上面只是一种解决思路。
 
 
-## 15、子应用请求接口报错
+## 14、子应用请求接口报错
   - 1、请确保接口请求没有跨域问题，因为子应用被加载到基座渲染，所以请求接口时origin为基座应用的域名。
 
   - 2、请求的接口为相对地址，会以基座域名进行补全，导致报错。

diff --git a/docs/zh-cn/start.md b/docs/zh-cn/start.md
@@ -120,7 +120,7 @@ export default function AppRoute () {
 
 #### ** Vue **
 ```js
-// mian.js
+// main.js
 import Vue from 'vue'
 import VueRouter from 'vue-router'
 import routes from './router'