From 65f57087770003a33e5b24c010a1a856171a5a03 Mon Sep 17 00:00:00 2001 From: chenqiushi Date: Thu, 19 Jul 2018 15:47:41 +0800 Subject: [PATCH] =?UTF-8?q?=20=E6=95=B4=E7=90=86=E9=83=A8=E5=88=86=20cli?= =?UTF-8?q?=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/basic/01-quick-start.md | 176 ++++++++++++++++++ docs/cli/start-writing-first-mip.md | 2 +- docs/new-doc/mip-cli/01-cli-usage.md | 139 ++++++++++++++ docs/new-doc/mip-cli/02-cli-user-plugin.md | 150 +++++++++++++++ .../mip-cli/03-start-writing-first-mip.md | 155 +++++++++++++++ .../mip-cli/04-component-development.md | 124 ++++++++++++ docs/new-doc/mip-cli/05-component-testing.md | 154 +++++++++++++++ docs/new-doc/mip-cli/06-component-deploy.md | 170 +++++++++++++++++ .../mip-cli/07-contribute-to-official-repo.md | 25 +++ .../08-contribute-to-site-extensions-repo.md | 86 +++++++++ 10 files changed, 1180 insertions(+), 1 deletion(-) create mode 100644 docs/basic/01-quick-start.md create mode 100644 docs/new-doc/mip-cli/01-cli-usage.md create mode 100644 docs/new-doc/mip-cli/02-cli-user-plugin.md create mode 100644 docs/new-doc/mip-cli/03-start-writing-first-mip.md create mode 100644 docs/new-doc/mip-cli/04-component-development.md create mode 100644 docs/new-doc/mip-cli/05-component-testing.md create mode 100644 docs/new-doc/mip-cli/06-component-deploy.md create mode 100644 docs/new-doc/mip-cli/07-contribute-to-official-repo.md create mode 100644 docs/new-doc/mip-cli/08-contribute-to-site-extensions-repo.md diff --git a/docs/basic/01-quick-start.md b/docs/basic/01-quick-start.md new file mode 100644 index 00000000..78100528 --- /dev/null +++ b/docs/basic/01-quick-start.md @@ -0,0 +1,176 @@ +MIP（Mobile Instant Pages - 移动网页加速器）主要用于移动端页面加速。 + +这篇文档将带你快速创建一个 MIP 页面。 + +## 1. 创建 HTML 文件 +首先创建一个标准的 HTML 文件，注意： + +- 在 `` 标签中增加 `mip` 属性标识。 +- 编码为 `utf-8` 。 +- 添加 `meta-viewport`，用于移动端展现。 + +```html + + + + + + Hello World + + +

Hello World!

+ + +``` + +## 2. 添加 MIP 运行环境 +在 HTML 代码中，添加 MIP 依赖的 `mip.js` 和 `mip.css` 。 + +```html + + + + + + + Hello World + + +

Hello World!

+ + + +``` + +## 3. 添加 MIP 关联标签 +`` 和 `` 主要用于告知搜索引擎页面间的关系。添加关联标签后，MIP 页的会继承 **原页面**(移动端) 的点击权重，同时 **MIP 页** 将作为搜索引擎的首选导流页面。 + +使用规则： + +- `` 在移动端页面（H5）使用，指向对应内容的 MIP 页，方便搜索引擎发现对应的 MIP 页。 +- `` 在 MIP 页中使用，指向内容对应的移动端页面（H5）。 +- 若没有移动端页面（H5），则指向内容对应的 PC 页。 +- 若直接在原链接修改 MIP，则 Canonical 指向当前 URL 。 + +```html + + + + + + + + + Hello World + + +

Hello World!

+ + + +``` + +## 4. 添加样式 +出于速度考虑，建议內联使用 CSS 样式。所有样式写在 `` 中，注意：`style` 标签仅允许出现一次。 + +```html + + + + + + + + + Hello World + + + +

Hello World!

+ + + +``` + +## 5. 替换禁用 HTML 标签 +MIP 十分关注页面速度，也因此禁用了一些引起拖慢速度的 HTML 标签（[禁用列表](../specs/mip-html-spec.md)）。例如，`` 标签会引起浏览器的 repaint 和 reflow，为了避免这些，MIP 提供了替代标签 `` ，详见 [``使用文档](../components/builtin/mip-img.md) 。 + +```html + + + + + + + + + Hello World + + + +

Hello World!

+ + + + +``` + +## 6. 使用 MIP 组件 +出于对代码质量和性能的考虑，MIP 页中不允许自定义 JavaScript 代码。 + +在一个合法的 MIP 页面中，所有的交互通过引入 MIP 组件实现。MIP 组件可以理解为封装了 JS 的自定义 HTML 标签。上一步中的 `` 也是一个 MIP 组件，[点击这里](../components/components-list.md) 查看更多组件。 + +我们以分享组件为例，根据[分享组件文档](../components/extensions/mip-share.md)，组件对应的 HTML 标签为 `` ，需要依赖 脚本，用在页面里就是这样： + +```html + + + + + + + + + Hello World + + + +

Hello World!

+ + + + + + +``` + +在使用组件时，请注意阅读组件文档，查看组件是否依赖所需脚本。如果依赖，请在 `mip.js` 之后引入脚本。 + +## 7. 预览 +开发完成后，可以使用 [MIP 校验工具](//www.mipengine.org/validator/validate) 保证代码规范。 + +[info] 校验代码，使用 [MIP 校验工具](//www.mipengine.org/validator/validate)。
预览线上 URL 异步打开效果，使用 [MIP 预览工具](//www.mipengine.org/validator/preview)。 + +MIP 页文件可以直接运行，你可以选择如下方式，像预览普通 HTML 站点一样预览 MIP-HTML 页面： + +- 直接在浏览器中打开（由于 XML HTTP Requests 失败可能会导致某些元素预览失败）。 +- 在本地部署一个服务，如 Apache，Nginx 等。 +- 使用 MIP-CLI 辅助预览，使用方法见[mip-cli 用法](../cli/cli-usage.md)。 + + +## 8. 起飞 +到目前为止，你已经创建好了一个 MIP 页面。这个页面有图、有文、能分享，可以在浏览器中运行。 + +进阶的内容，请参考： + +- [MIP-HTML 规范](../specs/mip-html-spec.md) +- [组件布局](../components/layout.md) +- [MIP 加速原理](./principle-of-mip.md) +- [扩展组件开发规范](../specs/mip-components-spec.md) + diff --git a/docs/cli/start-writing-first-mip.md b/docs/cli/start-writing-first-mip.md index 5f73184f..081d31ae 100644 --- a/docs/cli/start-writing-first-mip.md +++ b/docs/cli/start-writing-first-mip.md @@ -1,4 +1,4 @@ -# 快速开始 +# 使用 mip-cli 快速开始 - [编写第一个 MIP 页面](#编写-mip-页面) - [编写第一个 MIP 组件](#编写-mip-组件) diff --git a/docs/new-doc/mip-cli/01-cli-usage.md b/docs/new-doc/mip-cli/01-cli-usage.md new file mode 100644 index 00000000..80798722 --- /dev/null +++ b/docs/new-doc/mip-cli/01-cli-usage.md @@ -0,0 +1,139 @@ +# mip2 命令行工具 + +mip2 CLI 是官方提供的命令行工具，它提供了脚手架、调试、预览、校验、构建等功能，方便开发者快速开发 MIP 页面及自定义组件。 + +## 1. 依赖环境 + +mip2 CLI 使用 NPM 安装，依赖 Node 环境，推荐 + +- [Node.js](https://nodejs.org/) (>=8.x) + +- [Git](https://git-scm.com/) + +## 2. 安装 mip2 CLI + +打开命令行工具，输入： + +``` bash +$ npm install -g mip2 +``` + +输入 `mip2 -V`，若能正常显示版本号，说明已经安装成功。 + +## 3. mip2 CLI 使用 + +### 创建项目脚手架 + +``` bash +$ mip2 init +``` + +根据提示输入项目名 `myproject`，生成项目结构如下 + +```bash +myproject + ├── common // 组件公用代码，如 utils 等 + ├── components // 组件目录，编写组件代码 + │   └── mip-example + │   ├── mip-example.md // 组件功能、属性说明 + │   ├── mip-example.vue // 组件本身 + │   └── example + │   └── mip-example.html // 单个组件测试、预览 + ├── mip.config.js // 调试服务器配置 + ├── package.json + ├── static // 静态资源，如图片、字体 + └── example + └── index.html // 页面测试预览 +``` + +我们可以在项目的 `components` 目录中开发站点所需的自定义组件，然后依据 `example/index.html` 页面模板，引用官方或自定义组件来实现 MIP 页面。 + +通常情况下，官方提供的[通用组件库](https://github.com/mipengine/mip2-extensions)已经能满足站点的基本需求。如果站点有使用复杂组件的场景，我们可以[编写站长自定义组件](./08-contribute-to-site-extensions-repo.md)，并通过[站长组件仓库](https://github.com/mipengine/mip2-extensions-platform)进行提交，通过审核上线后，即能使用。 + +同时，我们也欢迎开发者向官方通用组件库[贡献优秀的组件](./07-contribute-to-official-repo.md)。 + +### 新增一个组件 + +在项目根目录运行 `mip2 add` 命令，即可快速添加一个新组件 + +```bash +# 快速添加名为 mip-new 的组件 +$ mip2 add mip-new + +# 使用 -f 或 --force 参数强制覆盖同名组件 +$ mip2 add mip-new -f +``` + +### 启动调试服务器 + +命令行工具内置了简单的调试服务器，方便开发者调试组件和页面。在项目根目录运行 + +``` bash +$ mip2 dev +``` + +默认会在 `8111` 端口启动服务器，并自动调起浏览器打开 `example/index.html` ，实现预览和调试。在修改组件和页面的代码时，无需手动重启和刷新，服务器内部已经帮我们实现了这一功能。 + +了解详细用法：[调试组件](./05-component-testing.md) + +### 组件和页面校验 + +MIP 组件和页面都需要遵循特定的[开发规范](../components/rules.md)，开发者提交站点 url 和组件代码时，系统会进行审核和校验。命令行工具提供了校验功能，方便我们在开发阶段就能按照相关规范进行开发和调整。 + +``` bash +# 校验 mip 组件，输入组件目录 +$ mip2 validate -c ./components + +# 校验 mip 页面，输入页面路径 +$ mip2 validate -p page.html +``` + +我们可以根据校验结果，对不符合规范的组件/页面进行相应的改进，校验通过后再进行提交。 + +### 构建组件 + +自定义组件开发完成后，可以使用 `mip2 build` 命令将组件代码打包成为对应的 `mip-组件名.js` 文件，供发布使用。 + +在项目根目录运行 + +``` bash +$ mip2 build +``` + +默认将在 /dist 目录产出打包压缩后的组件资源。了解详细用法：[组件构建](./04-component-development.md) + +### 生成 Service Worker + +mip2 CLI 提供了 `sw` 命令，帮助开发者更简单快速地生成 Service Worker，支持离线可用等特性。 + +``` bash +# 在项目根目录运行 +$ mip2 sw +``` + +默认情况下，将导出 Service Worker 文件到 `dist/sw.js`，并对静态资源(如 js,css)及 html 文档进行缓存，实现页面的离线可用。 + +`mip2 sw` 命令提供了选项： + +``` javascript +-o, --output // 指定 sw 导出路径，如 mip2 -o output/service-worker.js +-c, --config // 指定配置文件路径，默认使用项目根目录 mip.config.js +``` + +除此之外，我们可以在 `mip.config.js` 中增加 `serviceWorker` 配置项，对 Service Worker 进行进一步的配置，如预缓存列表、动态缓存策略、`skipWaiting`、`clientsClaim` 等。 + +``` javascript +module.exports = { + dev: {/*...*/}, + serviceWorker: { + cacheId: 'mipuser', + skipWaiting: true, + clientsClaim: true, + runtimeCaching: [], + globPatterns: [], + globIgnores: [] + } +} +``` + +更多的配置选项可以参考 [Workbox 配置项](https://developers.google.com/web/tools/workbox/modules/workbox-build#generateswstring_mode) diff --git a/docs/new-doc/mip-cli/02-cli-user-plugin.md b/docs/new-doc/mip-cli/02-cli-user-plugin.md new file mode 100644 index 00000000..8985a157 --- /dev/null +++ b/docs/new-doc/mip-cli/02-cli-user-plugin.md @@ -0,0 +1,150 @@ +# mip2 CLI 用户自定义扩展 + +除了内置的 `init`，`dev`，`add`，`validate` 等命令，mip2 CLI 亦提供了自定义扩展机制（mip2@1.1.0 及以上），开发者可以根据自身需求来开发相应的扩展命令，丰富命令行的功能。 + +## 使用自定义扩展命令 + +用户自定义扩展命令使用 npm package 的方式进行开发。我们约定，扩展包名为：**`mip-cli-plugin-{Command}`** + +如需使用自己或社区的扩展命令，无需手动进行安装，只需运行 `mip2 {Command}` 即可快速开始使用。 + +``` bash +# eg: 运行包名为 mip-cli-plugin-foo 的扩展命令 +$ mip2 foo +``` + +可以使用 `--help` 选项查看当前内置命令和扩展命令列表 + +``` bash +$ mip2 --help + +# Commands 是内置命令 +# User Plugins Comamnd 是扩展命令 + +Usage: mip2 [options] + +Options: +... +Commands: + +init 初始化 MIP 2.0 项目 +... + +User Plugin Commands: + +foo foo 扩展命令 +... +``` + +## 开发扩展命令（User Plugin Command） + +### 1. 创建项目 + +扩展命令的项目模板可以参考：[开发模板](https://github.com/mipengine/mip-cli-plugin-foo) + +我们可以参考模板创建一个结构相同的项目，或者直接 `clone` 项目模板，然后根据需要进行相应修改： + +```bash +git clone https://github.com/mipengine/mip-cli-plugin-foo +``` + +### 2. 开发 + +在开发模式中，我们可以使用 `npm link` 命令方便调试 + +```bash +cd mip-cli-plugin-foo +npm link +``` + +`npm link` 之后，运行 `mip2 --help` 就能看到我们的扩展命令已经出现在 User Plugin Command 中了。 + +扩展命令的项目结构如下： + +```bash +├── cli +│   ├── foo +│   │   └── bar.js // 对应子命令，mip2 foo bar +│   └── foo.js // 对应主命令，mip2 foo +├── index.js // 模块入口 +├── lib // 建议把业务逻辑写在 lib 目录 +├── package.json +└── README.md +``` + +`cli` 目录是命令的入口，所有的命令都应该放在这里。 +`mip2 foo` 会自动读取 `cli/foo.js` 对应的模块。同理： +`mip2 foo bar` 会自动读取 `cli/foo/bar.js` 对应的模块。 + +> 注意：模块名称与命令名称必须保持一致，否则会找不到对应的模块 + +#### 配置扩展命令 + +自定义扩展命令可以通过命令模块中的 `cli.config` 进行配置： + +``` javascript +config: { + // 命令描述信息，显示在命令列表说明中 + description: 'foo bar 功能测试', + + // 和 usage 一起组成 Usage 信息 + name: 'mip2 foo', + + // 表示 id 为必选参数，[id] 表示 Id 为可选参数 + usage: '', + + // 命令 options + options: [ + ['-f, --force', '强制执行'], + ['-p, --port ', '端口号'] + ], + + // 帮助信息， --help 时显示 + help: [ + '', + ' Examples:', + ' # 测试自定义 plugin 命令', + ' $ mip2 foo -f', + ' # 测试自定义 plugin 命令', + ' $ mip2 foo -p 8888' + ].join('\n') +}, +``` + +#### 扩展命令入口 + +`cli.main` 是命令执行的入口 + +``` javascript +/** + * 命令执行入口 + * + * @param {Array} 命令接收的参数数组 + * @param {Object} 命令配置的 options 对象。option 接收 时获取值，否则返回 boolean 类型 + */ +main: function (args, opts) { + // your own stuff + console.log('args: ') + console.log(args) + console.log('opts: ') + console.log('opts.force: ' + opts.force) + console.log('opts.port: ' + opts.port) +} +``` + +### 3. 发布 + +开发测试完成后，使用 `npm publish` 来发布命令扩展。 + +### 4. 使用 + +无需手动安装，直接运行即可 + +``` bash +$ mip2 foo +$ mip2 foo +$ mip2 foo --port +$ mip2 foo bar +$ mip2 foo bar --force +... +``` diff --git a/docs/new-doc/mip-cli/03-start-writing-first-mip.md b/docs/new-doc/mip-cli/03-start-writing-first-mip.md new file mode 100644 index 00000000..c3500114 --- /dev/null +++ b/docs/new-doc/mip-cli/03-start-writing-first-mip.md @@ -0,0 +1,155 @@ +# 使用 mip-cli 快速开始 + +- [编写第一个 MIP 页面](#编写-mip-页面) +- [编写第一个 MIP 组件](#编写-mip-组件) + +## 编写 MIP 页面 + +下面的步骤将带我们使用 [mip2 CLI](./01-cli-usage.md) 来快速创建一个 MIP 页面 + +### 1. 安装 mip2 CLI + +打开终端输入 + +```bash +$ npm install -g mip2 +``` + +### 2. 项目初始化 + +```bash +$ mip2 init +``` + +根据提示，输入项目名称等信息 + +### 3. 编辑页面模板 + +进入项目目录，使用编辑器打开 `example/index.html`，生成的模板已经为我们写好了 MIP 页面所需的最基本元素，如 `mip.js` 运行时，默认样式 `mip.css` 等。下面我们在页面中写入简单的内容，并使用内置 `mip-img` 组件。注意，如果使用其他非内置组件，需要在页面底部使用 `script` 标签引入相应的脚本文件。 + +```html + + + + + + MIP page + + + + + +
+

Hello World

+

This is my first MIP page.This is my first MIP page.This is my first MIP page.This is my first MIP page.This is my first MIP page.This is my first MIP page.This is my first MIP page.This is my first MIP page.

+ +
+ + + +``` + +### 4. 启动调试服务器预览 + +在项目根目录运行 + +```bash +$ mip2 dev +``` + +服务启动后，打开浏览器访问 `http://127.0.0.1:8111/example`，就能看到上面我们编写的页面的效果了。 + +## 编写 MIP 组件 + +下面的步骤将带我们使用 [mip2 CLI](./01-cli-usage.md) 来快速创建一个 MIP 自定义组件 + +### 1. 初始化项目 + +同上面的步骤类似，安装 `mip2 CLI` 工具后，我们运行 `mip2 init`，并创建一个名为 `myProject` 的项目 + +### 2. 新建一个自定义组件 + +在项目根目录运行 `mip2 add` 命令，即可快速添加一个新组件 + +```bash +# 快速添加名为 mip-hello-world 的组件 +$ mip2 add mip-hello-world + +# 使用 -f 或 --force 参数强制覆盖同名组件 +$ mip2 add mip-hello-world -f +``` + +可以在 `components` 目录下看到，新增组件结构如下： + +```bash +── mip-hello-world + ├── mip-hello-world.md + ├── mip-hello-world.vue + └── example + └── mip-hello-world.html +``` + +编辑器打开 `mip-hello-world.vue`，进行一定的修改 + +```html + + + + + + +``` + +### 3. 引用组件脚本 + +编辑器打开 `example/index.html`, 修改 `body` 部分的代码，引用组件脚本 + +```html +... + +
+

Hello World

+ +
+ + + + +... +``` + +### 4. 启动服务器预览 + +在项目根目录运行 + +```bash +$ mip2 dev +``` + +服务启动后，打开浏览器访问 `http://127.0.0.1:8111/example`，可以看到，刚才编写的组件已经运行在页面中。开发工作完成后，可以根据组件类型，选择将组件提交至第三方组件仓库(TODO)或[官方组件仓库](./07-contribute-to-official-repo.md)。 diff --git a/docs/new-doc/mip-cli/04-component-development.md b/docs/new-doc/mip-cli/04-component-development.md new file mode 100644 index 00000000..86ea26a8 --- /dev/null +++ b/docs/new-doc/mip-cli/04-component-development.md @@ -0,0 +1,124 @@ +# 组件开发说明 + +## 内置编译工具 + +mip-cli 的组件编译模块使用 webpack4 实现，内置了以下 loader： + +1. vue-loader: 默认将 `.vue` 文件编译成 `.js`，` +``` + +### 异步加载 + +`mip-cli@1.0.13` 以上版本支持模块异步加载，可通过 `import()` 或 `require.ensure()` 实现，这两个方法返回 Promise 对象，函数的具体说明可以查看 [webpack dynamic import](https://webpack.js.org/guides/code-splitting/#dynamic-imports)。 + +以 `import()` 举个例子，假设项目中需要用到 `mustache`，那么可以首先通过 npm 安装： + +```shell +npm install --save mustache +``` + +然后在编写组件代码时可以通过以下方式异步加载： + +```javascript +import('mustache').then(function (mustache) { + // 搞点事情 +}) +``` + +对于项目组件需要使用到的一些非 npm 模块，建议放在 `common/` 目录下，这样也可以通过相对路径的形式引入该模块。假设项目目录结构为： + +```bash +test-proj +... common/ +....... utils.js +... components/ +....... mip-example/ +........... mip-example.vue +... static/ +....... mip.png +... mip.config.js +``` + +假如需要在 mip-example.vue 中异步加载 utils.js，那么可以这么写： + +```javascript +import('../../common/utils').then(function (utils) { + // 搞点事情 +}) +``` + +需要注意的是，模块异步加载应该在组件的生命周期或者方法里调用，而不应该阻塞组件定义。举个例子，假设需要在 mip-example.vue 中异步加载 mustache，那么对应的 js 可以这么写： + +```javascript +// 变量缓存 +let mustache +// 加载 mustache 的方法 +async function getMustache () { + if (mustache) { + return mustache + } + + mustache = await import('mustache') + return mustache +} + +export default { + // ... + mounted() { + getMustache().then(function (mustache) { + // 搞点事情 + }) + } +} +``` + +## 沙盒机制 + +mip 在组件开发的时候限制使用 `window`、`document` 等对象或函数，在组件构建时，会将组件内使用诸如 `document.createElement()` 会被替换成 `mip.sandbox.document.createElement()`，在运行时会限制原有的能力，或者是直接抛出错误。 + +详情请阅读 [mip 沙盒机制](../util/sandbox.md) 进行了解。 diff --git a/docs/new-doc/mip-cli/05-component-testing.md b/docs/new-doc/mip-cli/05-component-testing.md new file mode 100644 index 00000000..5bda942e --- /dev/null +++ b/docs/new-doc/mip-cli/05-component-testing.md @@ -0,0 +1,154 @@ +# 组件调试 + +## 命令 + +mip-cli 提供了 `dev` 命令进行组件调试。 + +```shell +$ mip2 dev +``` + +## 引用方式 + +该命令会自动将当前目录下的 `components/` 下的 mip 组件进行编译并且进行改动监听，同时启动 node 服务器，默认端口为 `8111`，这样就可以通过以下方式去使用编译好的组件啦： + +```html + +``` + +同时，mip-cli 的 `dev` 命令也提供了一个静态服务器，允许开发者在 `test/` 目录和 `components/组件名/test/` 目录下写 `.html` 文件去进行组件调试。 + +比如文件路径为 `test/mip-example.html` 的页面，可以通过 `http://127.0.0.1:8111/example/mip-example.html` 进行访问，而 `components/mip-example/example/test-property.html` 则通过 `http://127.0.0.1:8111/components/mip-example/example/test-property.html` 进行访问。 + +在这种调试模式下，mip-cli 会自动注入 `livereload` 的脚本，让页面在开发时能够自动刷新网页。 + +**需要注意的是** + +mip-cli 默认调试模式均在本地进行，假设 mip-cli 在 dev 模式下编译产生的 js 文件需要供远端服务器调用进行联调，那么在启动 dev 的时候需要指定 --asset 参数或者使用简写 -a，比如： + +```shell +mip2 dev --asset http://192.168.0.10 +``` + +这样通过 `` 引入 js 才不会报错。 + +## 参数说明 + +`mip2 dev` 可以传入以下参数去修改默认配置： + +1. `-p --port`: 静态服务器的监听的端口号，默认为 8111； +2. `-a --asset`: 静态资源 publicPath，默认为 http://127.0.0.1:${port}； +3. `-d --dir`: 项目根目录，默认为 `process.cwd()`； +4. `-l --livereload`: 是否启动自动刷新，默认为 false； +5. `-o --autoopen`: 静态服务器启动后默认打开的网页，默认为空，即不打开任何页面； +6. `-c --config`: 读取 mip-cli 配置文件，默认为 `process.cwd()/mip.config.js`; + +mip-cli 允许通过配置 `mip.config.js` 去修改默认配置，比如： + +```javascript +// mip.config.js +const path = require('path'); + +module.exports = { + // dev 命令配置 + dev: { + port: 8222, // 默认端口从 8111 变更为 8222 + livereload: true, // 启动自动刷新 + autoopen: '/example/index.html' // 默认打开 http://127.0.0.1:8222/test/index.html + } +} +``` + +默认配置、mip.config.js、命令行参数的优先级为： + +```bash +默认配置 < mip.config.js < 命令行参数 +``` + +## 例子 + +假设通过 mip-cli init 出来的项目结构如下： + +```bash +test-proj/ +... components/ +....... mip-example/ +........... example/ +............... index.html +........... mip-example.vue +... example/ +....... index.html +... mip.config.js +``` + +其中 `mip.config.js` 的配置为： + +```javascript +module.exports = { + dev: { + port: 8222, + dir: './components', + livereload: true, + autoopen: '/example/index.html' + } +}; +``` + +`test/index.html` 的内容为： + +```html + + + + + + MIP page + + + + + + + + + + + + + +``` + +`components/mip-example/mip-example.vue` 的内容为： + +```html + + + + + + +``` + +在 `test-proj/` 目录下敲入命令行并回车： + +```shell +mip2 dev +``` + +此时会自动打开 `http://127.0.0.1:8222/example/index.html`，页面显示如下： + +![mip-example.jpg](https://gss0.baidu.com/9rkZbzqaKgQUohGko9WTAnF6hhy/assets/mip/docs/mip-example-a6d1f6f5.jpg) diff --git a/docs/new-doc/mip-cli/06-component-deploy.md b/docs/new-doc/mip-cli/06-component-deploy.md new file mode 100644 index 00000000..f461aef3 --- /dev/null +++ b/docs/new-doc/mip-cli/06-component-deploy.md @@ -0,0 +1,170 @@ +# 组件部署 + +> 通常情况下，组件开发者是不需要进行部署工作的，因为最终的构建部署上线工作都是 MIP 官方完成。 +> 但如果你是一名 MIP 组件测试工程是，在组件提交到 MIP 组件平台之前进行部署测试的话，还是需要对组件部署有一定的了解。 + +## 构建 + +### 构建命令 + +mip-cli 提供了 `build` 命令可以对 mip 组件项目进行打包构建。 + +```shell +$ mip2 build +``` + +#### 使用方式 + +该命令会将 `/comoponents` 目录下的下的 mip 组件进行编译，编译成功后会在 `/components` 同级目录生成一个包含所有构建后资源产物的 `/dist` 目录，如果需要将组件代码部署到指定的静态资源服务器进行测试，只需要将 `/dist` 内容部署到静态资源服务器即可。 + +#### dist 目录 + +在组件仓库项目的根目录执行了 `mip2 build` 命令之后，会在组件仓库项目根目录会生成一个 `/dist` 目录，`/dist` 目录的内容基本和 `/components` 目录的内容一一对应： + +```shell +# dist 目录的示例 +dist/ + |_ mip-demo-components1/ + |_ mip-demo-components1.js + |_ mip-demo-components2/ + |_ mip-demo-components2.js + |_ mip-components-webpack-helpers.js +``` + +这个 `/dist` 目录可以用来被部署到静态资源服务器，如 mip 线上部署 `/dist` 的静态资源服务器路径为 `https://m.mipcdn.com/static/v2/`，如果你是一名 mip 组件测试工程师，你就需要在提交组件仓库到 mip 官方上线之前，将 `/dist` 部署到自己的静态资源服务器相应的路径进行测试。 + +#### 参数说明 + +通过 `mip2 build -h` 命令可以查看构建命令的用法： + +```shell +Usage: mip2-build [options] + + Options: + + -a, --asset 静态资源 publicPath + -o, --output 编译代码输出路径 + -c, --clean 构建前先清空输出目录 + -i, --ignore 忽略沙盒注入 + -h, --help output usage information +``` + +##### asset + +`asset` 是一个指定静态资源 publicPath 的参数，为了让你在开发组件的时候可以直接通过相对路径的方式引入本地的静态资源，例如图片、字体文件、异步加载 js 文件等，默认的 `asset` 的值为 `/`。 + +为了更好的讲解清楚 `asset` 参数的作用，我们给一个具体的示例，假设 mip 组件项目的 `mip-demo-components` 组件源代码如下： + +```shell +# mip 的组件代码仓库目录的部分结构 +components/ + |_ mip-demo-components/ + |_ localpath-image.png + |_ mip-demo-components.vue +``` + +如果在 `mip-demo-components.vue` 中的 `