Weex Eros快速入门
DaLei 2019-06-29
概述
随着Weex跨平台技术的持续火热，一时间涌现出了一大批基于Weex的开源解决方案，Weex Eros就是这么一个面向前端Vue的开源APP解决方案。
目前，如果直接使用Weex框架开发应用会存在很多痛点，诸如初始化启动的环境问题、项目工程化问题、版本升级与版本兼容问题和不支持增量更新等，而Weex Eros等开源解决方案能对上述问题进行有效的解决。
Weex Eros的定位不是组件库，而是基于Weex封装的面向前端Vue的一整套APP开源解决方案，它关心的是整个APP项目。在Weex的强大支持下，用一份Vue代码即可编译出iOS、Android两端原生的app，并且通过Weex Eros内置的热更新逻辑和开源的服务器逻辑，开发的APP还具有热更新能力。
快速入门
工欲善其事，必先利其器。使用Weex Eros开发移动应用需要具备以下软件环境。
- Android 4.1 (API 16)
- iOS 8.0+
- WebKit 534.30+
环境搭建
除了安装一些必须的软件（如Node、Git等）之外，Weex Eros还依赖于脚手架eros-cli。全局安装命令如下：
npm i eros-cli -g
如果是在国内，还可以使用cnpm进行安装，或者直接修改下载的镜像地址，例如淘宝的镜像源。
cnpm i eros-cli -g //或者使用淘宝镜像安装 npm i -g cnpm --registry=https://registry.npm.taobao.org
同时，为了方便对Weex Eros程序进行断点调试，建议开发者安装Weex官方提供的脚手架命令行工具weex-toolkit。
cnpm i -g weex-toolkit
除此之外，为了能够正常的运行Android、iOS应用程序，因此还需要安装原生Android和iOS相关的运行环境。特别的，对于iOS来说，还需要安装诸如ruby、rubygems和cocoapods等工具软件。
工程创建
和使用weex cli创建工程类似，借助eros-cli脚手架工具可以很方便的创建Weex工程。例如：
eros init <工程名> <版本号> <模板> <Android包名>
使用eros init方式创建工程时，init后面依次跟的是项目名称、版本号、模板类型和安卓包名，除了项目名称外，其他都不是必须的。需要说明的是，同一个Android手机上不能出现2个包名相同的应用，所以命名时请注意区分。
然后进入工程目录，执行cnpm i安装node_modules依赖包，等待依赖包安装完成，打开模板工程目录结构。
├── config │ ├── eros.dev.js //脚手架相关配置 │ └── eros.native.js //客户端相关配置 ├── dist //静态资源生成目录 ├── node_modules //依赖 ├── scripts //自动化脚本 ├── platforms //平台基础代码 │ ├── android │ └── ios ├── src //开发路径 │ ├── assets //静态资源路径 一般存放图片 │ ├── iconfont //静态资源路径 一般存放 iconfont │ ├── js // js bundle 开发路径 │ └── mock //本地请求 mock 地址 ├── CHANGELOG.md //版本升级变动 └── package.json //npm项目及依赖说明
运行项目
使用eros init方式创建的项目，模板会默认生成Android、iOS原生工程结构。启动客户端之前，需要先使用eros dev指令启动服务端服务，启动过程中如出现任何的报错，请先按照错误提示解决报错问题。
运行iOS项目前，需要cd到iOS工程目录的platforms/ios/WeexEros中执行pod update命令来拉取iOS工程的依赖包。
pod update
命令执行完毕后，使用Xcode打开工程目录下WeexEros.xcworkspace文件即可打开iOS工程。
需要说明的是，最新版本的Xcode在导入iOS工程时会报错，如library not found for -lstdc++.6.0.9，请根据实际情况解决这些错误。然后，在Xcode中选择相应的模拟器，点击运行按钮即可启动iOS工程，运行效果如图8-4所示。
对于Android环境来说，使用Android Studio依次选择【File】→【New】→【Import Project】，找到eros工程目录，然后依次选择【platforms】→【android】→【WeexFrameworkWrapper】，点击【ok】按钮即可导入Android工程，如图8-3所示。
接下来，打开WeexFrameworkWrapper工程并执行工程下的install.sh脚步来安装Android工程所需要的依赖包nexus和wxframework。待Android工程构建完成，点击Android Studio工具栏上的【Run】按钮即可运行项目，运行效果如图8-4所示。
本地开发的时候，可以运行脚手架eros dev指令来启动本地服务，脚手架eros-cli会通过读取配置文件在特定端口启动服务，而客户端访问的就是工程目录下dist文件通过webpack打包生成的JS Bundle文件。
而生产环境客户端运行的版本一般都会内置一个JS Bundle文件，这样即使断网也不会出现页面空白的情况，而是读取本地内置包的内置数据。
Weex eros内置了拦截器开关，拦截器的主要作用就是控制加载js文件的方式。当拦截器处于打开状态时，会从当前工程内置的资源中加载js资源文件，否则从开发服务器上加载js资源文件。可以通过Interceptor开关来配置访问的是服务器开发包还是内置包，如图8-5所示。
Hello eros
新建一个Eros项目时，系统默认是开启Interceptor拦截器的，如果关闭调试中的拦截器，再让app访问服务包将会出现白屏。为了更好的理解Eros的加载流程，下面通过一个Hello Eros实例来说明。
首先，关闭调试拦截器，然后使用WebStrom打开Eros工程，并在pages目录下新建一个Hello.vue文件。
<template>
<div style="margin-top: 50px;">
<text class="title">Hello，</text>
<text class="title">developer</text>
<wxc-button class="btn-250" text="show eros" ></wxc-button>
</div>
</template>
<script>
import { WxcButton } from 'weex-ui';
export default {
components: { WxcButton }
}
</script>
<style>
.title{
font-size: 60;
}
.btn-250{
width: 250;
}
</style>修改eros.dev.js配置文件中的exports，如果不需要可以把eros-demo中对应的路径都删掉，只配置需要的文件入口。
"exports": [
"js/config/index.js",
"js/mediator/index.vue",
"js/pages/Hello.vue" //导出Hello.vue
],需要注意的是，eros.dev.js文件中的appBoard、mediator和eros.native.js是一一对应的，如果两边修改没有对应上会导致报错，建议不要随便变动。
要改变eros工程的首页，需要修改eros.native.js文件中的page.homePage路径。
"page": {
"homePage": "/pages/Hello.js",
}断开eros dev服务并重启服务，然后重新运行app即可看到示例效果，如图8-6所示。
很多时候，app会默认使用本地内置的JS bundle而不是从服务端下载。为了将编写好的代码打包成JS bundle，需要使用eros pack指令。
eros pack
eros pack打包指令提供了eros pack ios、eros pack android、eros pack all三个指令来为不同的平台进行打包操作，如图8-7所示。
然后，将打好的JS bundle包内置到Android的assets或iOS的工程目录下即可。然后，关闭调试拦截器，本地运行的即是内置的bundle包。
工程配置
在eros项目中，整个项目只有两个配置文件，都放在项目的config文件夹下，分别是eros.native.js和eros.dev.js。其中，eros.native.js表示客户端需要读取的配置信息，eros.dev.js表示开发环境需要读取的配置信息，该配置文件主要用来配置开发、调试、语法检测、mock、生成增量包和全量包等功能。
eros.native.js文件表示客户端需要读取的配置信息，eros.native.js文件的每次变动，都需要重新执行命令eros dev并重新运行app。例如：
{
appName: "eros-demo", //工程名称
appBoard: "/config/index.js",
androidIsListenHomeBack: "true", //监听Android物理返回键
customBundleUpdate: 'true', //配置更新jsbundle逻辑
version: {
android: "1.0.0", //Android版本号
iOS: "1.0.0" //iOS版本号
},
page: {
homePage: "/pages/eros-demos/index.js", //主页地址
mediatorPage: "/mediator/index.js", //中介页面地址
navBarColor: "#3385ff"，
navItemColor:"#ffffff"
},
url: {
image: "https://app.weex-eros.com/xxx/xxx", //图片上传路径
bundleUpdate: "http://localhosts:3001/app/check" //jsBundle更新接口
},
zipFolder: {
server: "home/app", //增量发布差分包地址
iOS: "/ios/WeexEros/WeexEros", //iOS本地包地址
android: "/android/WeexFrameworkWrapper/app/src/main/assets"
},
getui: {
enabled: "false", //是否开启个推服务
appId: "",
appKey: "",
appSecret: ""
},
tabBar: {
color: '#777777',
selectedColor: '#00b4cb',
backgroundColor: '#fafafa',
borderColor: '#dfe1eb',
list: [{
pagePath: '/pages/demo/router/tabbarItem1.js',
text: '首页',
icon: 'bmlocal://assets/[email protected]',
selectedIcon: 'bmlocal://assets/[email protected]',
navShow: 'true',
navTitle: "首页"
},
//省略其他配置
]
}
}如上，是一个典型的eros.native.js文件的配置信息，具体说明如下：
- appName：表示脚手架自动生成app的名称。
- version：表示脚手架自动生成的工程版本号，包含iOS和Android两个子版本号，可用于增量发布时的版本判断。
- androidIsListenHomeBac：用于配置Android平台是否需要监听首页的物理返回键。
- customBundleUpdate: 用于配置是否自定义更新jsbundle逻辑，默认为true，即不使用更新逻辑。
- page：用于配置与页面相关的内容，包含navBarColor、navBarColor、mediatorPage和navItemColor等子配置项。其中，homePage表示主页js的相对地址，mediatorPage表示中介者页面的相对地址。
- url：配置与路径相关的内容，包含jsServer、image和bundleUpdate等子配置项。其中，jsServer用于配置本地js服务路径，image用于配置图片上传的绝对路径，bundleUpdate用于配置jsBundle更新接口。
- zipFolder：用于配置内置包的存放地址，包含server、iOS和android等子配置项。其中，server表示部署在服务器上做增量发布的差分包地址，iOS表示iOS平台内置包地址，android表示Android平台内置包地址。
- getui：基于个推的推送服务实现配置，包含enabled、appId、appKey和appSecret子配置项。
除了上面的配置外，eros.native.js文件还有一个比较重要的配置tabBar，此配置选项用于配置原生tabBar的相关内容。如果您的app被设计成多tab的样式，那么tabBar配置将变得非常有用。
同eros.native.js配置文件一样，eros项目的另一个配置文件eros.dev.js也非常重要，此配置文件主要用来让开发者在开发环境，对开发、调试、语法检测、mock、生成增量包和全量包等进行配置。例如：
{
exports: [ //暴露的js页面文件
"js/service/bus.js",
"js/pages/home/index.js",
"js/pages/demo/index.js",
"js/pages/home/tab1/index.js",
"js/pages/home/tab2/index.js",
],
alias: { //文件别名
"Components": "js/components",
"Common": "js/common",
"Config": "js/config",
"Widget": "js/widget",
"Pages": "js/pages",
"Utils": "js/utils"
},
eslint: false, // eslint检查配置
server: { //服务的路径和端口配置
"path": "./",
"port": 8889
},
diff: {
"pwd": "/Users/yangmingzhe/Work/opensource/eros-diff-folder",
"proxy": "https://app.weex-eros.com/source"
},
proxy: [{ //代理配置
"route": "/test",
"target": "127.0.0.1:52077/test"
}],
mockServer: {
"port": 52077,
"mockDir": "./dist/mock"
},
socketServer: {
"switch": true,
"port": 8890
}
}如上，是一个典型的eros.native.js文件的配置信息，具体说明如下：
- exports：暴露出的页面对应的js地址，app中的每个页面本质上都对应一个js文件。
- alias：文件夹别名，用于更方便快速的访问。
- eslint：项目编译时是否需要进行eslint检查。
- server：运行eros dev服务的路径和端口配置，使用默认即可。
- proxy：代理相关的配置，使用默认即可，此配置会把/test路径对应的请求代理到127.0.0.1:52077/test。
- mockServer：本地mock数据服务。
- socketServer：用于配置热更新服务开关和端口。
开发调试
在根目录运行eros dev指令时，脚手架会在工程的根目录下生成dist文件用于存放JS Bundle。
对于本地开发环境来说，eros是默认开启调试功能的。如果要关闭debug功能，可以依次点击【Debug】→【Setting】→【Interceptor】来关闭拦截器，然后点击【Refresh】按钮或者双击屏幕上【Debug】按钮刷新页面，此时就会重新从服务器加载最新的 js文件。
同时，eros还支持热刷新功能，即修改代码保存(快捷键command + s)时页面会自动刷新，可以通过Setting面板的HotRefresh开关按钮来打开热刷新，如图8-8所示。同时，热刷新只有在eros dev服务已经启动，拦截器关闭的情况下才会生效。
如果要在真机上进行断点调试，需要重复上面的调试步骤。然后执行命令weex debug，执行完毕后系统会自动唤起Chrome浏览器打开调试主页，并展示出调试的二维码。
在App中点击调试按钮在弹出框中点击调试选项，并使用脚手架工具提供的扫一扫功能扫描调试的二维码，然后选择Debugger即可开始断点调试。
未完待续！！！
