Version: v5.2

NodeJS前端语言

该文档适用于nodejs前端类项目，比如vue、react。

NodeJS 前端项目识别方式

Rainbond 会根据源代码根目录是否有 package.json 和 nodestatic.json 文件来识别为NodeJS前端类项目，除此之外，源代码根目录下还必须存在以下两个文件之一（不可以同时存在）：

package-lock.json 存在该文件时，Rainbond 默认使用 npm 包管理器构建。
yarn.lock 存在该文件时，Rainbond 使用 yarn 包管理器构建。

验证准备

将项目部署到 Rainbond 之前，请按照以下步骤进行本地验证，本地构建成功后，即可开始尝试将项目部署在 Rainbond 上。

源代码托管于 Git 或 SVN 服务器。
检查本地构建环境与运行环境，确定 npm、 node、 yarn 版本。
清除本地构建缓存，一般情况下，本地项目路径下存在 node_modules 目录，请在确认后，将该文件夹临时更改路径。

mv node_modules node_modules.bak

执行以下构建命令，该命令也是 Rainbond nodejs 前端项目构建的默认命令：

# 使用 npm 进行构建时
npm run build

# 使用 yarn 进行构建时
yarn run build

编译运行环境配置

环境准备阶段，需要将 Rainbond 构建运行环境，和常用的本地构建运行环境尽量统一。比如 Node 版本、构建命令等。

图形化设置

Rainbond 支持图形化定义编译运行环境，配置位于服务组件的构建源页面。对这些配置的修改，需要通过构建来生效！

禁用缓存，在完成首次成功的构建之前，该开关应该始终处于打开的状态，默认关闭。
选择编译运行所使用的 Node 版本，务必使用验证准备时验证过的版本。
BUILD_NODE_ENV，用于指定构建过程中是否清理依赖，默认清理。
NPM MIRROR_URL，用于指定构建私服，默认指定淘宝 npm 源地址。
构建命令，用于指定项目通过什么命令构建，默认使用 npm run build 或 yarn run build ，取决于源代码根目录中具有 package-lock.json 还是 yarn.lock。

通过代码设置(推荐)

Nodejs 前端语言项目的编译运行环境可以通过代码进行设置。

package.json

该文件至关重要，平台根据其中 scripts 部分定义的 build 命令进行项目构建。基于 engines 部分定义的node、npm或者yarn版本进行环境配置。版本定义可以缺省，默认使用 node=10.9.0 yarn=1.9.4 npm=6.2.0 若你需要自定义版本，请按照如下格式配置：

"engines": {
    "node": "12.8.1",
    "npm": "6.4.1"
}

当前 Rainbond 支持如下 Node 版本：

选项	版本
Node	0.12.18, 4.9.1, 5.12.0, 6.14.4, 7.10.1, 8.12.0, 9.11.2, 10.13.0, 11.1.0, 12.8.1
Yarn	1.9.4

平台默认版本使用8.12.0。

package.json 文件中的 scripts 具备 CI 特征，Rainbond 源码构建过程继承这些特性，比如：

"scripts": {
    "preinstall": "bash preinstall.sh",     # 在执行 npm install 之前，自动执行脚本 preinstall.sh
    "postinstall": "bash postinstall.sh",   # 在执行 npm install 之后，自动执行脚本 postinstall.sh
    "build": "vue-cli-service build --mode test"   
}

更多 npm-scripts 特性，参考 How npm handles the "scripts" field

nodestatic.json

该文件指定静态文件编译后的输出目录，一般情况下，该路径都是 dist。

{
   "path": "dist"
}

web.conf

项目编译完成后，Rainbond 会默认使用 Nginx（1.14.2）将前端项目运行起来。用户可以在源代码根目录下加入 web.conf 文件来指定 Nginx 的配置，该文件的作用是定义运行时参数，特别是对后台API的代理。没有此文件时，Rainbond 会采用缺省配置。参考配置用例如下：

upstream upstream-server {
    server 127.0.0.1:8080;
}

server {
    listen 5000;
    
    location /api {
        proxy_http_version 1.1;
        proxy_set_header Host manage-server;
        proxy_pass http://upstream-server;
    }

    location /index.html {
        add_header Cache-Control "private, no-store, no-cache, must-revalidate, proxy-revalidate";
        try_files $uri $uri/ /index.html;
        root   /app/www;
        index  index.html index.htm;
    }
    location / {
        try_files $uri $uri/ /index.html;
        root   /app/www;
        index  index.html index.htm;
    }
}

配置文件格式与nginx配置文件方式一致。例子中/manage-server 为后端API的访问路径，代理到127.0.0.1:8080 ，然后前端组件需要依赖后端API组件。

rainbondfile

在源代码根目录下加入 rainbondfile 可以为服务组件定义环境变量，构建过程中更多的配置，可以通过环境变量的方式定义。

在 Rainbond 源码构建的过程中，为服务组件定义的 BUILD_ 开头的变量，可以被传入构建环境中使用。部分常用的环境变量如下:

环境变量	默认值	说明
BUILD_NPM_REGISTRY	`https://registry.npm.taobao.org`	执行 npm install 时指定的私服地址
BUILD_YARN_REGISTRY	`https://registry.npm.taobao.org`	执行 yarn install 时指定的私服地址
BUILD_NODE_ENV	`production`	用于指定构建过程中是否清理依赖，默认清理
BUILD_NODE_MODULES_CACHE	`true`	指定是否开启构建缓存，在 Rainbond 服务器磁盘性能低下时，指定为 `false`
BUILD_NODE_VERBOSE	`false`	指定是否在构建日志中体现依赖列表（`npm ls` 或 `yarn list`）

启动命令配置

Nodejs 前端项目源码构建过程完成后，Rainbond 会自动将服务组件运行起来，这需要我们事先指定服务组件的启动命令。

Procfile规范

Rainbond 通过源代码根目录下的 Procfile 文件来定义项目启动命令，Procfile 文件定义规范详见 Procfile 。

如果未定义Procfile，会生成如下默认Procfile

web: sh boot.sh

上述是默认 Procfile ,如果需要扩展更多启动参数,可以自定义 Procfile 。

web: 和 sh 之间有一个空格
文件结尾不能包含特殊字符

默认执行的 boot.sh 内容为：

sed -i -r  "s/(listen ).*/\1\$PORT;/" /app/nginx/conf.d/web.conf #使用指定的端口来配置 Nginx 监听
touch /app/nginx/logs/access.log
touch /app/nginx/logs/error.log
ln -sf /dev/stdout /app/nginx/logs/error.log
ln -sf /dev/stderr /app/nginx/logs/access.log
echo "Launching nginx"
exec /app/nginx/sbin/nginx -g 'daemon off;'

示例demo程序

示例https://github.com/goodrain/rainbond-ui

常见问题解决

使用 git-revision-webpack-plugin 插件打包时报错。
部分项目打包配置中设置了基于git来获取版本号，需要依赖源码目录中存在.git文件。在Rainbond中源码编译过程中使用的源代码不会存在.git文件。因此不能使用git插件来获取版本。Rainbond平台上有版本管理，因此遇到这个问题请移除webpack配置文件中的git相关的插件。
编译完成后访问404
请确认nodestatic.json 中配置的编译后文件发布目录是否是项目配置的发布目录。比如真实目录是 build，但 nodestatic.json 中配置的是 dist ，那最终就是找不到编译后文件。
平台上源码编译失败怎么办？
查看构建日志，大多数情况是属于源代码不符合规范或本身编译不通过导致。日志可以帮助你找到并解决问题。
（1）情景1，构建日志提示 Two different lockfiles found: package-lock.json and yarn.lock ，该信息提示当前源代码根目录下同时存在 package-lock.json 和 yarn.json 两个锁文件，请根据希望使用的包管理器删除另一个锁文件，提交代码后重新构建。
（2）情景2，构建日志提示：Outdated Yarn lockfile ，该信息提示当前构建使用的 yarn.lock 与 package.json 中规定的版本依赖有冲突，根据构建日志后续的提示，可以在本地更新 yarn.lock ，提交代码后重新构建。
（3）情景3，构建日志提示 No matching version found for Node: XXX 或 No matching version found for Yarn: XXX，该信息提示 package.json 中 scripts.engines 定义的 Node 、 Yarn 版本暂时不被支持，请参考上述文档 package.json 配置版本部分。如果 Rainbond 提供的版本的确不能满足项目需要，请联系好雨科技工程师添加。
（4）情景4，构建日志提示 Invalid semver requirement ，该信息提示 package.json 中 scripts.engines 定义版本的方式不符合 semver格式。请参考上述文档 package.json 配置版本部分。

源码编译通过但是运行异常。
（1）情景1，是因为没有定义 nodestatic.json 文件，平台认为这是nodejs后端项目。按照后端项目的方式去运行了。解决方式是源码中添加 nodestatic.json 文件，然后重新创建组件或者重新进行源码类型识别。然后重新构建。
（2）情景2，配置的web.conf格式不正确，不是合法的nginx配置。组件运行日志中会提示错误的行。

NodeJS 前端项目识别方式​

验证准备​

编译运行环境配置​

图形化设置​

通过代码设置(推荐)​

启动命令配置​

Procfile规范​

示例demo程序​

常见问题解决​