跳到主要内容

云引擎 Web 前端运行环境

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

信息

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

如果项目根目录包含一个 static.json 或 index.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.json 的 engines.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），如 postinstall、prepare 等。

备注

如果存在 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）、依赖安装命令（install）和构建命令（build），覆盖默认的行为：

leanengine.yaml
run: echo 'run another command'
install:
  - {use: 'default'}
  - echo 'install additional dependencies here'
build:
  - echo 'overwrite default build command here'

详细的说明见 Reference: leanengine.yaml。

系统级依赖​

在云引擎的线上环境中，开发者可以在 leanengine.yaml 中定义额外的系统级依赖：

leanengine.yaml
systemDependencies:
  - imagemagick

支持的完整列表见 Reference: leanengine.yaml。

构建日志​

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

如需打印完整的构建日志以便调试，可以在部署时勾选「打印构建日志」或命令行工具添加参数 --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 的区别见 域名绑定指南 § 云引擎域名。

时区​

云引擎使用北京时间（东八区）。