客户端开发指南

技术准备

喧喧客户端使用到了如下关键技术:

  • Electron:(最初名为 Atom Shell)是 GitHub 开发一个的开源框架。它允许使用 Node.js(作为后端)和 Chromium(作为前端)完成桌面 GUI 应用程序的开发。Electron 现被已多个开源 Web 应用程序用于前端与后端的开发,著名项目包括 GitHub 的 Atom 和微软的 Visual Studio Code
  • NodeJS:一个基于Chrome V8 引擎的 JavaScript 运行时;
  • npm:作为 nodejs 内置的包管理器;
  • ES6:(全称 ECMAScript 6.0) 是 JavaScript 语言的下一代标准,已经在2015年6月正式发布了;
  • React:一个为数据提供渲染为 HTML 视图的开源前端库;
  • Webpack:前端资源模块化管理和打包工具。

如果你了解以上一个或多个技术,以下内容你可以选择性的阅读以更快的进入喧喧开发状态;如果你是第一次接触这些内容也没有关系,这篇指南仍然可以带你将喧喧跑起来。

快速开始

如果你是 nodejs 开发老手,请了解如下关键命令,并且跳过下面的 详细步骤 章节。

$ git clone https://github.com/easysoft/xuanxuan.git
$ npm install
$ npm run dev

详细步骤

下面的内容适合新手,包含详细步骤和注意事项。

1. 安装 Nodejs 和 npm

访问 Nodejs 官网下载并安装 nodejs,选择一个适合你的操作系统的安装包,按照官方提示安装即可。虽然不同的 nodejs 版本都可以运行喧喧,但可能需要额外的配置,建议你下载与喧喧开发者相同版本的 nodejs 版本。喧喧开发人员目前使用的 nodejs 环境版本是 7.8.0,可以在这个页面 https://nodejs.org/zh-cn/download/releases/ 找到对应版本的下载地址。

Windows 和 Mac 系统用户可以直接下载非常方便的一键安装包,安装完成后打开命令行窗口(Mac 下为应用 “终端”,Windows 下为程序 “命令提示符” 或 “PowerShell”)输入如下命令查询安装后的版本号,如果输出正确版本号说明安装成功。

$ node -v

输出:

v7.8.0

如果 nodejs 安装成功,npm 也会一起安装完成,输入npm -v来检查已安装的 npm 版本。

$ npm -v

输出:

4.2.0

2. 下载喧喧源码

如果你的系统安装有 git,只需要在命令行执行如下命令来下载最新版的喧喧源码:

$ git clone https://github.com/easysoft/xuanxuan.git

下载完成后就会在你的系统创建一个名称为xuanxuan的目录,该目录内就是喧喧最新的源码。

如果你还没有安装或使用过 git 也不用担心,你仍然可以访问 喧喧在 Github 上的页面,直接点击 “Download ZIP” 来下载源码。下载完成后将 zip 文件解压到xuanxuan目录下即可。

3. 安装项目依赖

从命令行进入下载好的喧喧源码目录(以下默认为xuanxuan/),执行如下命令:

$ npm install

安装失败?

此步骤通常需要几分钟,视网络环境执行的时间不定。如果你使用的是国内网络,可能导致某些依赖模块安装失败。下面介绍使用国内 淘宝 NPM 镜像 来加速安装过程,确保安装成功。以下经验适合任何基于 nodejs 的项目。

使用 cnpm

在你的终端执行:

$ npm install -g cnpm --registry=https://registry.npm.taobao.org

这样你就可以使用cnpm命令来代替npm了,这样可以执行如下命令来安装喧喧的项目依赖:

$ cnpm install
将镜像地址写入~/.npmrc

在你的系统找到~/.npmrc文件,并用文本编辑器打开,写入如下内容到文件:

registry=https://registry.npm.taobao.org/
disturl=https://npm.taobao.org/dist

注意:.npmrc文件在系统的个人文件目录下,在不同的操作系统上对应的路径不同,Windows 用户通常此文件在C:/Users/UserName/.npmrc,Mac 用户通常此文件在/Users/UserName/.npmrc。

写好配置后可以使用npm info命令检查下是否生效,以下为查看 ZUI 示例:

$ npm info zui

如果在命令行输出信息的结尾找到 ZUI 的下载地址为registry.npm.taobao.com,说明配置生效了。

dist:
   { shasum: '134f986bc53a62be2310a0438918b8a17b58c80c',
     size: 9957159,
     noattachment: false,
     tarball: '**http://registry.npm.taobao.org/zui/download/zui-1.6.0.tgz**' },
  publish_time: 1489730305654 }

这样再次执行npm install命令就可以使用国内的淘宝镜像进行依赖模块的安装了。

安装 Electron 失败?

设置 ELECTRON_MIRROR 环境变量

设置 Electron 环境变量,在 Mac 或 Linux 下执行:

$ export ELECTRON_MIRROR="https://npm.taobao.org/mirrors/electron/"

Windows 用户可以打开系统属性面板来设置环境变量或者执行如下命令:

$ set ELECTRON_MIRROR=https://npm.taobao.org/mirrors/electron/

做了如上设置后,请重新执行npm install。

单独安装 Electron

如果仍然遇到问题,你可以尝试单独先安装 Electron,Mac 或 Linux 用户执行:

ELECTRON_MIRROR="https://npm.taobao.org/mirrors/electron/" npm install electron

Windows 用户无法运行上面的命令,需要先安装cross-env,执行:

$ npm install cross-env

然后再执行:

ELECTRON_MIRROR="https://npm.taobao.org/mirrors/electron/" npm install electron

这样就可以强制从淘宝镜像安装 Electron。

其他资源

如果你还有其他问题,请参考如下内容:

4. 启动开发服务器

如果你最后一次执行npm install没有出现任何错误,就可以启动开发服务器了。

启动 React 热更新服务器

在命令行窗口执行如下命令:

$ npm run hot-server

如果你在命令行窗口看到如下内容,说明 React 热更新服务器成功启动:

npm run hot-server 运行成功截图

热更新服务器用于监听源码文件更改,当你更改了源码之后会立即重新编译并通知界面组件进行刷新。这是一种所见即得的开发模式,也就是说你在源代码中的更改会即时反馈到界面上来。

注意:只有 React 组件模块会直接在界面上更新,如果是其他模块虽然仍然会实时编译,但并不会进行实时更新,此时你可以在界面上按页面刷新快捷键(Windows 为F5,Mac 用户为Command+R)来重新载入界面。

启动客户端

打开一个新的命令行窗口(不要关闭之前打开的正在运行的热更新服务器命令行窗口)执行:

$ npm run start-hot

如果你在命令行窗口看到如下内容,说明客户端启动成功:

npm run start-hot 运行成功截图

一步到位

启动 React 热更新服务器和客户端可以通过一个命令一步到位:

$ npm run dev

不过这种方式的缺点是无法单独查看热更新服务器和客户端调试的输出信息。你可以根据自己的习惯选择合适的启动方式。

恭喜

通常情况下,如果以上步骤都成功,此时会在你的屏幕左侧打开一个新的窗口:窗口上方是喧喧的界面,下方是 Chrome 的开发者工具。

成功启动客户端

打包

正常打包

任何时候执行如下命令可以为所在平台(Windows 用户打包 Windows 安装包,Mac 用户打包 Mac dmg 安装镜像)打包喧喧安装程序:

$ npm run package

对于 Windows 用户,默认情况下,如果你的系统是 64 位,则打包的是 Windows 64 位版本,如果你的系统是 32 位,则打包的是 32 位安装包,如果你需要在 Windows 64 位系统上打包 32 位版本,则需要执行:

$ npm run package-win-32

打包调试版本

执行如下命令,可以打包一个调试版本方便用户安装并进行调试:

$ npm run package-debug

调试版会像开发模式启动的客户端一样在界面下方显示 Chrome 的开发者工具,并且不会忽略所有调试消息。

跨平台打包(仅适合 Mac 用户)

如果你是 Mac 用户,除了可以打包 Mac 安装镜像,还可以打包 Windows 安装包和 Linux 安装包,这样实现在一个平台上打包所有平台版本。

确保你的系统安装了 brew 来安装跨平台打包的依赖工具。

执行如下命令为打包 Windows 版本做准备:

$ brew install wine --without-x11
$ brew install mono

执行如下命令为打包 Linux 版本做准备:

$ brew install gnu-tar graphicsmagick xz

如果你还需要构建 Linux rpm 包,则需要安装 rpm:

$ brew install rpm

完善上述步骤之后就可以使用如下命令来构建所需的平台版本了:

命令 说明
npm run package-win 打包 Windows 64 位版本
npm run package-win-32 打包 Windows 32 位版本
npm run package-linux 打包 Linux 64 位版本
npm run package-linux-32 打包 Linux 32 位版本
npm run package-win-debug 打包 Windows 64 位**调试**版本
npm run package-browser 打包浏览器端版本
npm run package-all 同时打包所有平台上的版本

源码结构

下面简单介绍喧喧源码(假设以下根目录为xuanxuan/)各个目录及文件内容:

目录 介绍
/app/ 客户端源代码
/app/assets/ 客户端使用到的第三发静态资源目录
/app/media/ 客户端上用到的图片、语音及表情资源
/app/lang/ 客户端语言配置文件目录,目前只有中文简体文件 `zh-cn.json
/app/style/ 客户端界面样式表文件目录,通常为 Less 文件
/app/utils/ 客户端用到的工具组件
/app/network/ 客户端内部与网络相关的接口模块
/app/config/ 客户端配置文件
/app/platform 客户端与平台相关的模块
/app/core/ 客户端核心模块
/app/components/ 客户端界面用到的通用 React 组件
/app/views/ 客户端界面 React 视图组件
/app/main.development.js Electron 入口文件
/app/index.html 主窗口 HTML 代码文件
/app/index.js Electron 主窗口入口代码文件
/resources/ Electron 打包时用到的资源文件目录
/server/ 服务器端源代码目录
/server/xxd/ XXD 服务器端源代码目录
/server/ranzhi 然之协同服务器端扩展源代码目录

其他

如果你遇到针对此指南或者喧喧开发过程中任何问题,欢迎加入 QQ 群 367833155 讨论。

    关键字