云引擎 Web 前端运行环境

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

信息

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

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

快速开始

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

React

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

Vue

可以使用官方的 Vue CLI：

npm install -g @vue/cli
vue create vue-for-engine

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

static.json

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

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

leanengine.yaml

build: npm run build

Next.js

可以使用官方的 create-next-app 创建项目：

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

然后切换到项目目录（上面的例子中是 next-for-engine），创建一个 leanengine.yaml 来配置构建命令：

leanengine.yaml

build: npm run build

信息

为了能使用 Next.js 提供的 API Routes 等功能，这里实际是运行在 Node.js 运行环境（使用 npm start 启动 Next.js production server），因此下文中关于配置 serve 的部分并不适用于 Next.js。

云引擎可以在线上完成构建过程，开发者不需要将构建产物提交进 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` 版本。

配置包管理器

云引擎目前支持以下包管理器：

• npm
• pnpm
• Yarn 1
• Yarn 2+

云引擎会按照以下条件使用包管理器：

包管理器	条件	版本
pnpm	存在合法能被解析的 pnpm-lock.yaml
	lockfileVersion: '6.0' 或更高	8
	lockfileVersion: 5.3 或更高	7
	其他	6
Yarn 1	存在 yarn.lock	1
Yarn 2+	不默认支持，需通过 Corepack 启用	2+
npm	其他情况	使用 Node.js 默认提供的 npm

实验性 Corepack 支持

由于 Corepack 还是实验性特性，云引擎不能保证对 Corepack 的支持是稳定的

通过给分组设置 ENABLE_EXPERIMENTAL_COREPACK 环境变量为任意非空字符串来启用实验性 Corepack 支持。

云引擎会通过调用 Corepack 读取 package.json 里的 packageManager 字段来自动识别、使用用户指定的包管理器，这也是目前唯一一种使用 Yarn 2+ 的方式。

假设有以下 package.json：

package.json

{
  "name": "example",
  "packageManager": "yarn@4.0.2"
}

此时云引擎会自动调用 corepack prepare --activate 并识别包管理器为 Yarn 2+。

参考：Corepack

默认命令

云引擎默认运行的脚本会随着包管理器的变化而变化，如使用了 pnpm， npm ci 会变成 pnpm install --frozen-lockfile。

云引擎只有在没有指定 installDevDependencies 为 true 且构建脚本为空（没有手动指定，package.json 里的 scripts.build 不存在）时才会省略 devDependencies 的安装。

阶段	包管理器	条件	命令
install	npm	Node.js 10 以上且存在 package-lock.json 或 npm-shrinkwrap.json	npm ci
			npm install 或 npm install --omit=dev
	pnpm		pnpm install --frozen-lockfile 或 pnpm install --frozen-lockfile --prod
	Yarn 1		yarn install 或 yarn install --production
	Yarn 2+		yarn install

备注

请注意 Yarn 1 只会使用 yarn.lock 内解析的 URL 下载依赖且不会遵循用户设置的源，请选择合适的源，否则可能会增加构建时间。

安装依赖（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 等。

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

备注

云引擎会上传 .yarn 文件夹，所以如果启用了 Yarn 2+ 的 PnP（Plug'n'Play）但不想使用 Zero-installs，请将 .yarn/cache 加入到 .gitignore 和 .leanignore 中

配置 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 的区别见 域名绑定指南 § 云引擎域名。

时区

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