阮喵喵自用的 vercel 部署工具

生成满足 Vercel Output API （v3）规范的目录结构，并推送到 vercel 平台内。

目前仅考虑简单的静态页面，没有实现云函数等功能。

设计初衷

• 优化冗长的 github action 写法。
• 同时支持 monorepo 和单体项目的部署。
• 自动实现文件移动，避免用户自写文件移动命令。
• 实现复杂部署任务的并列执行，提高运行性能。
• 配置实现类型提示，对用户友好。
• 实现单一 vercel 项目的多项目部署，绕开 vercel 针对 monorepo 项目的部署限制。

安装

1pnpm i -D @ruan-cat/vercel-deploy-tool@latest

环境要求

• node >=20.15.1
• pnpm >=9

使用教程

增加 .gitignore 配置

本工具会在根目录内默认生成一个全空配置的 vercel.null.def.json 文件，这个文件应该被忽略。

后续的使用会不可避免的使用 vercel 的 api，会在你的项目内生成一个或多个.vercel 文件夹，故.vercel 文件夹也应该被忽略。

1# 忽略vercel本地打包生成的文件
2.vercel
3# 忽略自动生成vercel部署配置文件
4vercel.null.def.json

如果你使用环境变量文件，推荐你加上 dotenv 推荐的环境变量文件忽略。

1# dotenv environment variable files
2.env
3.env.development.local
4.env.test.local
5.env.production.local
6.env.local

获取 vercel 提供的 id

用 vc link 命令获取 vercelOrgId 和 vercelProjectId。

你可以明文地写在配置上面，也可以考虑放在环境变量，放在 github secrets 环境变量内。

放在项目内的 .env 环境变量文件内（可选）

举例如下：

1VERCEL_PROJECT_ID=prj_your_vercel_projectId
2VERCEL_ORG_ID=team_your_vercel_orgId
3VERCEL_TOKEN=your_vercel_token

环境变量必须写成大写，名称很严格。如果你使用环境变量的方式提供这些值，请务必使用例子提供的变量名。

编写部署配置文件

1// .config/vercel-deploy-tool.ts
2import { type Config } from "@ruan-cat/vercel-deploy-tool/src/config.ts";
3
4const config: Config = {
5	vercelProjetName: "prj_your_vercel_projectName",
6	vercelOrgId: "team_your_vercel_orgId",
7	vercelProjectId: "prj_your_vercel_projectId",
8	// 默认留空即可
9	vercelToken: "",
10
11	deployTargets: [
12		{
13			type: "userCommands",
14			outputDirectory: "docs/.vuepress/dist/**/*",
15			targetCWD: "./",
16			url: ["small-alice-web-dev.ruancat6312.top", "small-alice-web.ruan-cat.com"],
17			userCommands: ["pnpm -C=./ vuepress-vite build docs"],
18		},
19	],
20};
21
22export default config;

编写运行文件

1// bin/vercel-deploy-tool.ts
2// 执行部署任务
3import "@ruan-cat/vercel-deploy-tool/src/index.ts";

封装运行命令

在 package.json 内提供命令

1{
2	"engines": {
3		"node": ">=22.6.0",
4		"pnpm": ">=9"
5	},
6	"scripts": {
7		"deploy-vercel": "node --import=tsx ./bin/vercel-deploy-tool.ts"
8	}
9}

这里采用直接运行 typescript 文件的方案运行部署工具，你需要额外多安装 tsx 依赖：

1pnpm i -D tsx

运行 pnpm run deploy-vercel 命令就能部署项目到 vercel 了。

配置 github action（可选）

1name: 自写的vercel部署工具
2env:
3  # 必须密文提供token
4  VERCEL_TOKEN: ${{ secrets.vercel_token }}
5  # 可以明文提供组织id和项目id
6  # VERCEL_ORG_ID: ${{ secrets.vercel_orgId }}
7  # VERCEL_PROJECT_ID: ${{ secrets.vercel_projectId }}
8
9on:
10  push:
11    branches:
12      # 可以自选分支 为了避免过快耗尽vercel额度，建议只在main分支内触发部署
13      - main
14
15jobs:
16  Deploy-Production:
17    runs-on: ubuntu-latest
18    steps:
19      - name: 检出分支
20        uses: actions/checkout@v4
21
22      - name: 安装pnpm
23        uses: pnpm/action-setup@v4
24        with:
25          # 若项目提供了packageManager配置 这里可以不提供该配置
26          # version: 9
27          # 必须安装 vercel @dotenvx/dotenvx tsx 这三个全局包
28          run_install: |
29            - recursive: true
30            - args: [--global, "vercel", "@dotenvx/dotenvx", "tsx"]
31
32      - name: 安装node
33        uses: actions/setup-node@v4
34        with:
35          node-version: 20.15.1
36          cache: pnpm
37
38      - name: 检查版本
39        run: |
40          node -v
41          pnpm -v
42          vc -v
43
44      - name: pnpm全局检查依赖包
45        run: pnpm ls -g
46
47      - name: 运行自写的vercel部署工具
48        # 读取环境变量
49        # https://dotenvx.com/docs/cis/github-actions#install-dotenvx
50        # pnpm run your-command
51        run: |
52          curl -sfS https://dotenvx.sh/install.sh | sh
53          pnpm dotenvx run -- pnpm run deploy-vercel

路线图

• 封装打包命令，vc deploy 命令，并赋予生产环境 url。
• 拆分配置文件到项目根目录，并实现文件读取。
• github action 运行产物。
• github action 全局安装新开发的包，实现纯工作流的部署。
• 去其他项目，自主完成配置与部署。
• 封装 node 的 bin 命令，发包。