Vercel部署：前后端分离项目的整体部署流程及问题排查

Vercel 整体部署流程：

前后端分离，有两个 github 仓库，在Vercel 上注册后，直接拉取 git 代码，自动进行部署。

前端使用 vite, vue3，后端使用 node.js，express。 Vercel 均能自动识别架构并给予部署流程建议。

【注册时，发现用 github 账号直接注册，会进行校验账号，注册失败。后来换了谷歌浏览器，使用gmail邮箱注册，注册成功。】

1. Vite+TS 项目构建报错：找不到@ 别名模块的 bug 排查记录。
2. 使用 husky，在 pre-commit 钩子中，使用 lint-staged 库，执行vue-tsc --noEmit,会检查 node_modules 依赖中的ts。
3. serverless function 项目的vercel.json配置文件如何写。
4. 前后端跨域，vercel 环境配置参数。

1. Vite+TS 项目构建报错：找不到 @ 别名模块的bug排查记录

1.1 问题背景

在 Vite + TypeScript 项目中，执行 vue-tsc --noEmit 时无报错，但运行 vue-tsc -b && vite build 时，提示找不到 @/xxx 模块（尤其是引入 @ 开头的组件或工具函数时）。

1.2 问题原因

• TS 配置文件分工不明确 ：Vite 项目通常存在 tsconfig.json、tsconfig.app.json、tsconfig.node.json 三个配置文件，其中：

  • tsconfig.node.json 负责编译 Vite 配置文件（如 vite.config.ts），但未配置 paths 别名；
  • tsconfig.app.json 负责编译 src 目录下的业务代码，若 paths 与根目录 tsconfig.json 不一致，也可能导致问题；
  • 根目录 tsconfig.json 虽配置了 paths，但通过 references 引入子配置时，子配置不会自动继承 paths。

• 缺少显式 include 配置 ：tsconfig.node.json 未明确指定需要编译的文件（如 vite.config.ts），导致 TypeScript 可能误读配置范围。对该文件所在的目录文件及子文件夹文件，都采用此文件进行编译，但未配置path路径别名，故报错"@"找不到模块。

2. 使用 husky，在 pre-commit 钩子中，使用 lint-staged 库，执行vue-tsc --noEmit,会检查 node_modules 依赖中的ts。

2.1 问题背景

在git提交时，使用 lint-staged 对暂存文件进行 vue-tsc 类型检查，发现报错 node_modules 依赖中的很多类型问题，发现 lint-staged 运行时，忽略了 tsconfig.json 配置文件中的 exclude 选项。前端的 tsconfig.json 代码如下：

 {
  // 编译器选项配置，用于控制 TypeScript 编译器的行为
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    // 配置路径映射，这里将以 @/ 开头的导入路径映射到 ./src/ 目录下，方便导入项目内的模块
    // 允许导入 JSON 文件并将其视为模块，导入后可以像使用普通模块一样使用 JSON 数据
    "resolveJsonModule": true,
    // 指定要包含的类型声明文件，这里包含了 Vite 客户端、Node.js 和 naive-ui 的 Volar 插件的类型声明
    "types": [
      "vite/client",
      "node",
      "naive-ui/volar",
      "@vue/runtime-core"
    ],
    // 启用所有严格类型检查选项，确保代码的类型安全性
    "strict": true,
    // 强制文件名大小写一致，避免在区分大小写的文件系统上出现问题
    "forceConsistentCasingInFileNames": true,
    // 跳过对类型声明文件（.d.ts）的类型检查，加快编译速度
    "skipLibCheck": true
  },
  // 指定要引用的其他 tsconfig 文件，用于项目的模块化配置
  "references": [
    // 引用应用程序相关的 tsconfig 配置文件，配置独立，不会继承当前文件的配置
    {
      "path": "./tsconfig.app.json"
    },
    // 引用 Node.js 相关的 tsconfig 配置文件
    {
      "path": "./tsconfig.node.json"
    }
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

2.2 问题原因

lint-staged 执行命令时，可能导致 vue-tsc 无法正确读取 tsconfig.json 的 exclude、compilerOptions 等配置。 我们需要使用系统命令，确保其在独立 shell 环境中加载配置。

package.json 代码配置如下：

{
  "$schema": "https://json.schemastore.org/package.json",
  ...
  "lint-staged": {
    "*.{ts,tsx,vue}": [
      "pnpm lint:fix",
      "sh -c 'vue-tsc -noEmit"
    ]
  }
}

3. serverless function 项目的vercel.json配置文件如何写 or 前端请求后端接口，报404。

3.1 问题背景

前后端分离项目，部署 express 开发的后端项目时，因为无需显示执行 build 命令，所以在 package.json 中，需要有 build、start对应的 scripts ,Vercel会自动执行这些命令。否则项目部署会出错。还需要配置vercel.json，将所有的路由映射到项目的入口文件，否则 Vercel 会把所有的前端请求当作静态资源请求，会报 404 。【注意参数实效性，很多参数已不支持，在千问获取的配置内容是过时的，卡了很久。】

3.2 问题原因

后端的 package.json 相关代码如下：

{
  "name": "",
  "version": "1.0.17",
  "private": true,
  "main": "build/index.js",
  "scripts": {
    "start": "node build/index.js",
    "dev": "esno watch ./src/index.ts",
    "build": "tsc",
    "prod": "node build/index.js",
    "clean": "rimraf build",
    "lint": "eslint",
    "lint:fix": "eslint --fix",
    "common:cleanup": "rimraf node_modules && rimraf pnpm-lock.yaml"
  },
...
}

后端的 vercel.json 代码如下【$schema一用，就知道哪些参数已经过时，还是得翻 Vercel 官方配置文档，不要轻信 ai 结果，给的都是过时的参数。】：

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "version": 2,
  "buildCommand": "npm run build",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/build/index.js"
    }
  ]
}

4. 前后端跨域，vercel 环境变量配置。

4.1 问题背景

本地测试时，前端项目可以使用 vite 的开发服务器，使用 vite.config.json 配置中的 proxy 进行服务代理。但在线上部署时，代理服务不生效，故需要后端使用 cors 中间件，进行域名请求限制。

本地使用 .env 文件，代码中使用 dotenv 库进行注入，在代码中直接使用process.env.Variables 进行使用，这些变量需要配置在 Vercel 的 Environment Variables 中。

4.2 问题解决

在 Vercel 的 Overview 主页面中，鼠标点击三个点进行配置部署好的项目，点击 Settings 进入项目配置。

点击 Environment Variables ，本人项目配置的变量有：前端项目需要配置后端的接口地址，后端项目需要配置前端的域名地址。

例如前端项目所需要的自定义环境变量如下：

后端在 express 项目入口文件，使用 cors 中间件，配置跨域请求。app.use(cors()) 在 router 创建之前。代码如下：

//app.js

import cors from 'cors'
import dotenv from 'dotenv'
import express from 'express'

dotenv.config()

// 创建 Express 应用实例
const app: Application = express()

// 配置 CORS 中间件
app.use(cors({
  origin: process.env.VITE_FRONTEND_URL, // 允许指定前端 URL 或所有来源访问
  credentials: true, // 允许跨域请求携带凭证
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], // 允许的 HTTP 方法
  allowedHeaders: ['Authorization', 'Content-Type', 'Accept'], // 允许的请求头
}))

// 创建 Express 路由实例
const router = express.Router()

部署总结：

配置好后，成功部署。前端域名正常访问，接口正常访问。

• 【 Vercel 部署的域名可以不公开，可以设置密码才能访问，但需要升级 pro 版本，才给这个功能。】
• 一定要看一下 ai 给出答案的文章参考时间，很多文档都是过时的，代码参数也是过时的。最快的还是翻官方文档。
• $schema很有用。
• 如果部署失败，看部署失败日志，很多错误会有提示。
• 在 logs 里，可以看到项目的访问情况，比如访问接口的地址，但返回消息体的详细数据，还是得在开发人员工具里看。
• 部署环境有 preview 和 production ,可以使用 preview 环境，新建一个 git 分支，当 git 推送更新时，Vercel 会自动检测并部署到 Preview ,可以在这进行测试。