云引擎 Node.js 运行环境
这篇文档是针对 Node.js 运行环境的深入介绍,如希望快速地开始使用云引擎,请查看 快速开始部署云引擎应用。
所有 Node.js 项目都必须在根目录包含一个 package.json 和启动脚本(如没有在控制台或 leanengine.yaml
内指定,请确保 package.json
内的 scripts.start
存在)才会被云引擎正确识别,云引擎也会从中读取项目对于环境的 需求:
{
"name": "node-js-getting-started",
"scripts": {
"start": "node server.js",
"dev": "nodemon server.js -- "
},
"dependencies": {
"leancloud-storage": "^3.11.0",
"leanengine": "^3.3.2"
},
"devDependencies": {
"nodemon": "^1.18.7"
},
"engines": {
"node": "16.x"
}
}
如果你希望创建一个新的项目,推荐从我们的 Node.js 示例项目 开始。
启动命令
云引擎默认使用 npm start
来启动项目,你可以在 package.json
中修改 scripts.start
来使用不同的程序入口或向 node
添加额外的参数。
{
"scripts": {
"start": "node server.js"
}
}
在使用 命令行工具 本地调试时,lean up
会优先使用 npm run dev
来启动项目。
配置 Node.js 版本
在 package.json
的 engines.node
字段可以指定 Node.js 版本:
{
"engines": {
"node": "16.x"
}
}
你还可以设置为 *
表示总是使用最新(current)版本。
如未设置 Node.js 版本,云引擎会默认使用最新的稳定(LTS)版本。
配置包管理器
云引擎目前支持以下包管理器:
云引擎会按照以下条件使用包管理器:
包管理器 | 条件 | 版本 |
---|---|---|
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
:
{
"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
中的依赖:
{
"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
中
自定义构建过程
除了默认的构建过程和运行命令外,开发者还可以在 leanengine.yaml
中进一步地调整运行命令(run
)、依赖安装命令(install
)和构建命令(build
),覆盖默认的行为:
run: echo 'run another command'
install:
- {use: 'default'}
- echo 'install additional dependencies here'
build:
- echo 'overwrite default build command here'
详细的说明见 Reference: leanengine.yaml
,下面是一些具体的例子:为子项目安装依赖
install:
- use: default
- require:
- ./frontend/package.json
- ./frontend/package-lock.json
- cd frontend && npm ci
build:
- npm run build
- cd frontend && run build
这里我们在保留默认行为的同时,额外为 frontend
目录下的项目安装了依赖、运行了构建命令。
系统级依赖
在云引擎的线上环境中,开发者可以在 leanengine.yaml
中定义额外的系统级依赖:
systemDependencies:
- imagemagick
支持的完整列表见 Reference: leanengine.yaml。
构建日志
默认情况下构建过程中产生的日志不会显示到控制台,只有构建失败时,最后一个步骤的日志才会被显示在控制台上。
如需打印完整的构建日志以便调试,可以在部署时勾选「打印构建日志」或命令行工具添加参数 --options 'printBuildLogs=true'
。
健康检查
云引擎目前主要为 Web 应用优化,应用在启动后需要在环境变量 LEANCLOUD_APP_PORT
中指定的端口上提供 HTTP 服务,注意需要监听在 0.0.0.0
地址(所有接口)上,而不是一些框架默认的 127.0.0.1
。
在应用部署时,云引擎的管理程序会每隔一秒去检查应用是否启动成功,如果超过启动时间限制(默认 30 秒)仍未启动成功,即认为启动失败,部署会中止。在之后的运行过程中,也会有定期的健康检查来确保应用正常运行,如果健康检查失败,云引擎管理程序会自动重启你的应用。
健康检查会通过 HTTP 检查应用的首页(/
),如果返回 HTTP 2xx 的响应,就视作成功。
点击展开健康检查与云引擎 SDK 的关联
云引擎还会尝试检查由 SDK 处理的 /__engine/1/ping
,如果 SDK 接入正确,便不再要求首页(/
)返回 HTTP 2xx。
如果 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 云引擎 > 管理部署 > 你的分组 > 设置 > 云函数模式 设置为「开启」或 leanengine.yaml
中 functionsMode
设置为 strict
,云引擎会检查 SDK 是否被正确地接入,否则会视作启动失败。
点击展开自定义启动时长(startupTimeout
)
启动时间限制默认为 30 秒,可设置范围为 15–120 秒,如需延长或缩短,可以在 leanengine.yaml
文件中设置:
startupTimeout: 60
云端环境
绑定自定义域名
云引擎需要设置域名才能访问。在 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 云引擎 > 管理部署 > 你的分组 > 设置 > 访问域名 处可以绑定域名。
如果你绑定的域名以 stg-
开头(如 stg-api.example.com
),会自动关联到预备环境。