跳到主要内容

云引擎 Web 前端运行环境

云引擎同样对托管 Web 前端应用(例如一个网站)提供了支持,对于使用了 React、Vue 等框架的应用,云引擎可以在线上完成构建的过程,开发者不需要将构建产物提交进 Git 仓库也不需要额外的 CI 环境。云引擎还提供了自定义域名绑定、自动申请 SSL 证书、重定向到 HTTPS 等常用的功能,减轻前端开发者在部署和运维环节的工作量。

信息

这篇文档是针对 Web 前端运行环境的介绍,如需了解云引擎平台提供的功能,请看 云引擎平台功能

如果项目根目录包含一个 static.jsonindex.html,云引擎就会将其识别为 Web 前端项目,使用 Node.js 运行环境进行构建,然后自动使用 serve 来启动一个 HTTP 服务器。

快速开始

大多前端脚手架都可以通过简单地配置运行在云引擎上,推荐使用它们来创建新的项目。

create-react-app 提供了开箱即用的 React 工具链,会自动配置好 React 的构建工具链,让开发者能专注在核心功能上:

npx create-react-app react-for-engine --use-npm

然后切换到项目目录(上面的例子中是 react-for-engine)创建一个配置文件 static.json 将不存在的 URL 都重写到 index.html,以便我们的单页应用可以使用自己的前端路由(如 react-router):

static.json
{
"public": "build",
"rewrites": [{ "source": "**", "destination": "/index.html" }]
}

再创建一个 leanengine.yaml 来配置构建命令:

leanengine.yaml
build: npm run build

云引擎可以在线上完成构建过程,开发者不需要将构建产物提交进 Git 仓库,也不需要额外的 CI 环境。

部署到云引擎

直接部署到生产环境:

lean deploy --prod

配置 Node.js 版本

package.jsonengines.node 字段可以指定 Node.js 版本:

package.json
{
"engines": {
"node": "16.x"
}
}

你还可以设置为 * 表示总是使用最新(current)版本。

备注
对于新创建的应用,如未设置 Node.js 版本,云引擎会默认使用最新的稳定(LTS)版本。在 2021-09-02 之前创建的分组因兼容考虑会默认使用 `0.12` 版本。

安装依赖(package.json

云引擎会自动安装 package.json 中的依赖:

package.json
{
"dependencies": {
"leancloud-storage": "^3.11.0",
"leanengine": "^3.3.2"
},
"devDependencies": {
"nodemon": "^1.18.7"
}
}

在安装依赖的过程中,云引擎会正常触发 NPM 的生命周期脚本(Life Cycle Scripts),如 postinstallprepare 等。

备注

如果存在 package-lock.json,云引擎会优先使用 npm ci 安装依赖(需要 Node.js 10 以上)。否则云引擎会使用 npm install --production 安装依赖(这意味着 devDependencies 中的依赖不会被安装)。

备注

如果存在 yarn.lock,云引擎会优先使用 yarn 安装依赖(需要 Node.js 4.8 以上)。如果不希望在云端使用 Yarn,请将它们加入 .gitignore(Git 部署时)或 .leanignore(命令行工具部署时)。请注意 yarn.lock 中包含了下载依赖的 URL,请选择合适的源,否则可能会增加构建时间。

因为云引擎会在云端安装依赖,所以命令行工具默认也不会上传 node_modules 目录;如果使用 Git 部署,也建议将 node_modules 目录添加到 .gitignore 中,使其不加入版本控制。

配置 serve

你可以在项目根目录创建一个 static.json 来配置 serve 的行为。

static.json
{
"public": "build", // 在 build 目录而不是项目根目录启动网站
"rewrites": [
{ "source": "**", "destination": "/index.html" } // 将所有不存在的文件的请求重定向到 index.html(适用大部分单页面应用)
]
}

更多 serve 的选项和用法见 serve-handler · Options

自定义构建过程

除了特定语言默认的构建过程外,云引擎还提供了一种通用的自定义构建过程的能力,这些选项可以在 leanengine.yaml 中设置。

run 覆盖运行命令

leanengine.yaml
run: $(npm bin)/serve -c static.json -l ${LEANCLOUD_APP_PORT}

支持 Shell 语法(如引用环境变量等)。

install 覆盖依赖安装命令

覆盖默认的依赖安装命令(如 npm install),或在安装依赖前后运行自定义命令。

leanengine.yaml
install: npm

多数 runtime 有默认的依赖安装命令,可以用 {use: 'default'} 来引用默认的命令:

leanengine.yaml
install:
- { use: "default" }
- npm run install-additional

依赖安装步骤默认只会将依赖清单(如 package.json 等文件)加入构建目录,如需其他文件可以用 require 来引入:

leanengine.yaml
install:
- require:
- frontend/package.json
- frontend/package-lock.json
- cd frontend && npm ci

build 覆盖构建命令

leanengine.yaml
build: npm run build

在构建阶段全部代码文件都已经被加入了构建目录。

支持用数组来表示多条命令,支持 Shell 语法:

leanengine.yaml
build:
- echo 'building'
- NODE_ENV=production $(npm bin)/webpack

少数 runtime 有默认的构建命令,可以用 {use: 'default'} 来引用默认的命令。

构建日志

默认情况下构建过程中产生的日志不会显示到控制台,只有构建失败时,最后一个步骤的日志才会被显示在控制台上。

如需打印完整的构建日志以便调试,可以在部署时勾选「打印构建日志」或命令行工具添加参数 --options 'printBuildLogs=true'

云端环境

绑定自定义域名

云引擎需要设置域名才能访问。在 云服务控制台 > 云引擎 > 你的分组 > 设置 > 访问域名 处可以绑定域名。

如果你绑定的域名以 stg- 开头(如 stg-api.example.com),会自动关联到预备环境。

负载均衡和加速节点

所有对云引擎的 HTTP 或 HTTPS 请求都会经过负载均衡,负载均衡组件会处理 HTTPS 加密、重定向到 HTTPS、对响应进行压缩等一般性工作,因此云引擎上的程序不需要自己实现这些功能。同时负载均衡带来的一些限制,在云引擎程序内进行修改也无法越过,如:

  • /.well-known/acme-challenge/ 开头的路径被用于自动管理证书,不会转发到云引擎程序。
  • 请求头(URL 和 header)每行最大 8K,总计最大 64K。
  • 请求体积(上传文件体积)最大 100M。
  • 连接或等待响应的超时时间为 60 秒。

重定向到 HTTPS

在绑定云引擎自定义域名时,可以选择「强制 HTTPS」,勾选后负载均衡组件会将 HTTP 的请求重定向到 HTTPS 的同一路径。

警告

在使用加速节点的情况下,「强制 HTTPS」选项无法正确工作,仍需 在项目代码层面实现重定向

加速节点缓存

如果你将自定义域名解析到加速节点(也包括云引擎的共享域名),那么加速节点会对请求进行缓存,加速节点会有一些默认的缓存规则。

默认会缓存的情况:

  • 响应头中有 Last-Modified(通常是静态资源,其中 HTML 最多缓存 60 秒)。

不会缓存的情况:

  • 出错的响应(非 2xx)。
  • 非幂等请求(如 POST)。
  • 响应头中没有 Last-Modified(通常是动态接口)。

默认的缓存时长取决于文件类型和 Last-Modified(越不常修改的文件缓存越久),你可以通过自行设置 Cache-Control 来覆盖默认的行为,边缘节点会尽可能遵守其中的要求,比如:

  • 设置 Cache-Control: no-cache 来避免响应被缓存。
  • 设置 Cache-Control: max-age=3600 来设置缓存时长(一小时)。
信息

如果希望完全避免被缓存机制影响,可以开通独立 IP 来绕过加速节点,更多关于加速节点与独立 IP 的区别见 域名绑定指南 § 云引擎域名

时区

云引擎使用北京时间(东八区)。