阿里云函数计算（FC）全栈部署实战文档：Vue + FastAPI 前后端分离项目

李日升sg

89人浏览 · 2026-06-07 22:39:19

李日升sg · 2026-06-07 22:39:19 发布

基于真实项目 Precruit（简历与招聘智能匹配平台）的完整部署经验整理。
涵盖 FC 环境配置、代码构建、自定义域名、环境变量、CORS、前端调用后端以及常见“坑”与解决方法。
最后更新：2026-06-07，基于实际可用的配置。

📌 目录

前置准备
后端（Python FastAPI）部署
前端（Vue）部署
自定义域名与路由配置
前后端联调与 CORS 处理
环境变量与安全实践
踩坑记录与解决方案
一键部署？AI 时代的展望

1. 前置准备

阿里云账号（已完成实名认证）
开通函数计算 FC 3.0 服务
一个已备案的域名（可选，强烈建议绑定,否则只有社区提供的域名，不能稳定使用）
GitHub 仓库存放项目代码（支持自动构建）

2. 后端（Python FastAPI）部署

2.1 项目结构示例

text

Precruit/
├── app/
│   ├── api/
│   │   └── main.py          # FastAPI 应用实例
│   ├── agents/              # 业务逻辑（LangGraph等）
│   └── ...
├── frontend/                # Vue 项目（下节）
├── main.py                  # 🚀 启动入口（关键！）
├── requirements.txt
└── .gitignore

2.2 `main.py` 启动文件内容（实际使用的配置）

"""Precruit API 启动入口"""
import uvicorn

if __name__ == "__main__":
    uvicorn.run(
        "app.api.main:app",
        host="0.0.0.0",
        port=9000,
        workers=1,
    )

2.3 FC 控制台创建函数

进入 FC 控制台 → 服务及函数 → 创建服务（如 precruit-backend）
创建函数 → 使用自定义运行时 (Debian10)
- 运行环境：Python 3.10
- 代码来源：GitHub（授权后选择你的项目）
- 启动命令：python3 main.py
- 监听端口：9000
- 执行超时时间：120 秒（根据项目启动时间适当调大）

2.4 环境变量配置（关键安全项）

我这个项目需要在函数配置中添加类似于如下的环境变量，别的项目也是同理

Key	Value	说明
`DEEPSEEK_API_KEY`	`sk-xxxxx`	调用 DeepSeek 模型（必须）
`EMAIL_PASSWORD`	`xxx`	邮件服务密码

⚠️ 注意：这些环境变量必须配置在 FC 函数的环境变量中，不能写在代码里或提交到仓库。
代码中通过 os.getenv("DEEPSEEK_API_KEY") 读取。

2.5 依赖安装（构建阶段）

在 FC 控制台的 代码和构建配置 中：

构建环境：Python 3.10（可选，主要用于安装依赖）
构建命令（如果函数需要离线安装依赖）：
```
mkdir -p python && pip install -r requirements.txt -t ./python
```
这里构建环境会生成一个 python 目录，FC 会自动将其加入 PYTHONPATH。
若函数代码包本身已包含所有依赖，可以不设构建命令。

我的配置界面：

3. 前端（Vue）部署

3.1 项目结构

frontend/
├── src/
├── public/
├── package.json
├── vite.config.js
├── .env.production          # 生产环境变量（关键！）
└── .env.development         # 开发环境变量

3.2 FC 控制台创建函数

创建另一个服务（如 precruit-frontend），函数名为 frontend。
运行环境：自定义运行时 (Debian10) —— 因为前端是静态文件，需要静态服务器。
代码来源：GitHub → 仓库 Precruit，分支 master
代码包路径：dist（构建产物目录）
构建环境：Node.js 20
构建命令（实际成功配置）：
```
cd frontend && npm install --registry=https://registry.npmmirror.com && npm run build && cp -r dist ./dist && cd ..
```
解释：进入 frontend 目录安装依赖、执行构建，然后将生成的 dist 文件夹复制到当前目录（即根目录）下，命名为 dist。
这样 FC 在打包代码包时就能从根目录的 dist 取得静态文件。
启动命令：npx -y serve -s . -l 9000
- 因为代码包里只有静态文件，需要启动一个静态服务器。
- -s . 表示以当前目录为根，并支持 SPA 路由 fallback（对 Vue Router history 模式至关重要）。
- -l 9000 监听 9000 端口，与 FC 要求一致。
监听端口：9000
执行超时时间：60 秒（默认即可）
单实例并发度：100（默认）

我的配置界面：

3.3 环境变量：前后端联调的关键

3.3.1 为什么不能用 FC 运行时环境变量？

在构建过程中，Vite 会将 VITE_ 开头的环境变量编译进 JS 产物。如果你在 FC 控制台配置 VITE_API_BASE_URL，它是在运行时才能读到的，而 Vite 构建发生在构建阶段，因此无法感知。
正确做法：创建 frontend/.env.production 文件，写入：

VITE_API_BASE_URL=https://xxxx.cn-hangzhou.fcapp.run(从FC控制台去拿这个地址)

然后将该文件提交到 Git 仓库。FC 构建时 Vite 会自动读取，并将值硬编码到 JS 中。

3.3.2 安全疑虑：后端地址暴露在前端代码中？

✅ 这是安全的。后端地址本身就是公开的，用户打开浏览器 F12 就能看到。真正的敏感信息（如 API Key、数据库密码）必须留在服务端环境变量中，永远不要放到 .env.production 或前端代码里。

3.4 前端代码配合

在 API 调用文件中（例如 src/api/index.js）：

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api'

const api = axios.create({ baseURL: API_BASE_URL, timeout: 180000 })

开发环境：使用 /api + Vite 代理（vite.config.js 中配置 proxy）指向本地后端 http://localhost:8000。
生产环境：.env.production 中的完整 URL 会被使用。

3.5 验证构建产物

部署后，在浏览器中打开前端页面，按 F12 → Sources → 找到 main.js（或 index-xxx.js），搜索 getApiBaseUrl 或直接查找后端地址。应该看到类似：

function Lue(){ 
  return"https://xxx.cn-hangzhou.fcapp.run"
}

localhost:8000 彻底消失即成功。

4. 自定义域名与路由配置

这里可以通过设置子域名来在FC里面多弄几个项目，比如baidu.com,你可以在改成: 项目名.baidu.com

4.1 目的

前端地址：http://xxx.xxx
后端 API 地址：http://xxx/api/*
避免跨域，统一入口，同时解决默认域名强制下载问题。

4.2 步骤

在 FC 控制台添加自定义域名：

进入 域名管理 → 添加自定义域名。
域名：xxx
协议：HTTP（HTTPS 可后加）

路由配置（顺序重要）：

路径	服务	函数	说明
`/api/*`	`precruit-backend`	`backend`	所有 API 请求转发到后端
`/*`	`precruit-frontend`	`frontend`	其余请求（页面、静态资源）转发到前端

在 DNS 服务商处添加 CNAME 记录：
- 登录域名托管控制台（阿里云 DNS 或其它）。
- 添加记录：
  - 主机记录：@（或 www）
  - 记录类型：CNAME
  - 记录值：FC 提供的公网 CNAME（例如 xxx.cn-hangzhou.fc.aliyuncs.com）
等待 DNS 生效（通常几分钟至半小时）。

4.3 注意事项

后端路由需要与 FC 路由路径匹配。例如后端定义 @app.post("/api/analysis/submit")，FC 路由 /api/* 原样转发，后端能正确接收。
若后端路由不带 /api 前缀（如 /analysis/submit），则需要 FC 路由配置路径重写，较复杂。建议统一为带 /api 前缀。

5. 前后端联调与 CORS 处理

5.1 联调流程

前端构建时注入正确的后端地址（通过 .env.production）。
部署后访问自定义域名 http://xxx。
浏览器 F12 → Network，观察请求是否发往 http://xxx/api/...。
若看到状态码 200 并返回数据，联调成功。

5.2 CORS 配置

当使用自定义域名统一入口（前端和后端同域）时，理论上不需要额外 CORS 配置，因为浏览器认为同源。
但如果直接使用后端独立的 .fcapp.run 域名，就需要 CORS。

推荐方案：使用自定义域名统一入口，无需额外 CORS 配置。

备选方案：若仍遇到 CORS 错误，可在后端代码中添加 CORS 中间件（FastAPI 示例）：

python

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://xxx.homes"],   # 生产环境前端指定域名
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

5.3 联调常见问题

请求仍然发到 localhost:8000
→ 检查 .env.production 是否被提交，重新触发 FC 构建；在浏览器 Source 面板确认 JS 中已硬编码正确地址。
CORS 报错
→ 确认是否使用了自定义域名且路由配置正确。如果仍报错，可添加后端 CORS 中间件。

6. 环境变量与安全实践

6.1 前端环境变量（公开信息）

可以放进 .env.production 并提交到仓库的：后端 API 地址、应用名称、第三方前端 SDK 密钥（公开的）等非敏感信息。
绝对不能放进前端的：API Key、数据库密码、任何私密 token。因为这些会直接编译到 JS 中，任何人都可查看。

6.2 后端环境变量（敏感信息）

必须在 FC 函数配置的“环境变量”中设置，如 DEEPSEEK_API_KEY、SILICONFLOW_API_KEY 等。
代码中通过 os.getenv() 读取。
不要写在代码文件里，更不要提交到 Git。

6.3 最佳实践

将 .env.production 提交到仓库（仅含公开地址）。
将 .env（无后缀）加入 .gitignore，其中存放开发时使用的假密钥。
在 FC 控制台单独配置生产环境密钥。

7. 踩坑记录与解决方案（速查表）

问题现象	根本原因	解决方案
Python 源码编码错误	未声明编码或 Python 2	文件头加 `# -- coding: utf-8 --`，务必使用 Python 3.10 运行时
`DEEPSEEK_API_KEY must be set`	环境变量缺失或未读取	FC 函数配置中添加环境变量；代码中用 `os.getenv` 读取
后端启动失败 `operation not permitted`	启动命令错误或端口未监听 9000	确保 `python3 main.py` 中 uvicorn 的 `port=9000` 且 `host="0.0.0.0"`
前端构建 `Invalid working directory`	代码包路径指向不存在的目录	构建命令最后将产物复制到根目录的 `dist`，代码包路径填 `dist`
前端启动报 `package.json` 缺失	启动命令需要 Node 环境但静态文件无 `package.json`	启动命令改为静态服务器：`npx -y serve -s . -l 9000`
访问 FC 默认域名下载 HTML	`.fcapp.run` 域名强制添加 `Content-Disposition: attachment`	绑定自定义域名，使用自定义域名访问
前端请求仍发往 `localhost`	环境变量未注入构建过程	创建 `frontend/.env.production` 并提交，重新构建
CORS 错误（使用自定义域名时通常无此问题）	前后端不同域	使用自定义域名统一入口，或后端添加 CORS 中间件
自定义域名访问 `/api/xxx` 返回 404	后端路由路径不匹配	确保后端路由也带 `/api` 前缀；或检查 FC 路由配置是否正确

8. 一键部署？AI 时代的展望

虽然当前我们仍需要手动配置 FC 环境、填写构建命令、处理域名，但已经在向 AI 辅助部署演进。

可用的 AI 工具（2026 年）：
- 对话式平台：Meoo（秒悟）、万小智 2.0 — 用自然语言生成并部署全栈应用。
- MCP 集成：Blink Cloud + Cursor — 在编辑器中用自然语言触发部署。
- 云厂商镜像：Hermes Agent — 预制 AI 应用镜像，分钟级部署。
建议：对于学习、中小项目，当前 FC 手动部署仍然免费且可控；对于追求极致效率的场景，可以尝试上述 AI 工具。