Weex Eros快速入门

概述

随着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/[e-mail]',
                selectedIcon: 'bmlocal://assets/[e-mail]',
                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即可开始断点调试。

未完待续！！！

附：weex-eros示例

weex-eros入门