构建指南

本章将介绍 Pages 部署的构建步骤及其工作原理。

在创建项目时,使用预设模板的情况下,Pages 将采用模板的默认配置进行构建;而对于导入的 GitHub 仓库,Pages 会自动识别所使用的框架,并应用最常见的构建配置。

如果您需要特定的设置,可以在创建新项目时或在项目设置中自定义根目录、编译命令和输出目录等参数。

您可以通过两种方式启动 Pages 部署:
将代码变更推送到 GitHub
在控制台里面启动重新部署


构建设置

您可以从「项目设置 - 构建部署配置」指定 Pages 如何构建您的项目。





框架预设

通过下拉菜单选择预设的框架,可以快速填充各个配置项。选择框架后,您仍然可以继续调整其他配置。


根目录

根目录是执行编译命令的路径,如果未设置,默认为存储库的根目录 ./


输出目录

输出目录是存放构建产物(如 HTML 文件和静态资源)的路径。该目录相对于根目录,默认为 root ( / )。您可以通过 框架指南 查询不同框架对应的输出目录。


编译命令

Pages 会根据所选框架自动设置编译命令,例如 npm run build。编译命令将在 Bash shell 中运行,您也可以添加与 Bash 兼容的语法。

有关不同框架对应的编译命令,请参阅 框架指南


安装命令

Pages 在构建时会自动检测安装命令,从 package.json 安装依赖项。默认为 npm instal

目前支持的包管理器如下:
包管理器
Lock 文件
安装命令
支持版本
Yarn
yarn.lock
yarn install
1
npm
package-lock.json
npm install
8, 9, 10
pnpm
pnpm-lock.yaml
pnpm install
6, 7, 8, 9


Node 版本

Pages 预装了 14.21.3、16.20.2、18.20.4、20.18.0、22.11.0 几个 node 版本,您可以在「项目设置 - Node.js 版本」进行选择。



注意:
预装的 node 版本里提供 pnpm、yarn、bun 等包管理器,若项目根目录里有 .nvmrc 会自动下载并切换至指定版本,但不包含相应的包管理器。


环境变量

Pages 支持使用环境变量来构建您的项目。每个环境变量由一个变量名和一个变量值组成,目前这些变量对所有环境均有效。
您对环境变量的任何更改将不会影响之前的部署,这些更改仅适用于新的部署。
注意:
变量名的长度限制为 255 个字节,变量值的长度限制为 500 个字节