部署设计器前端

设计器前端是 CatPull 的可视化拖拽编辑器，基于 Vue 3 + Vite 构建，部署为静态资源由 Nginx 托管。

属性	值
技术栈	Vue 3 + Vite
默认端口	80（Nginx）
源码目录	catpull-v3/catpull-designer
构建产物	catpull-designer/dist/

配置环境变量

编辑 catpull-designer/.env 文件：

# API 请求前缀（通过 Nginx 反向代理到后端）
VITE_ORIGIN=/api

# 腾讯云 COS 存储桶名称
VITE_COS_BUCKET=your_cos_bucket
# 存储桶所在地域
VITE_COS_REGION=ap-guangzhou
# 云函数请求地址
VITE_URL_CLOUD=

# 项目预览地址
VITE_PREVIEW_SERVICE_URL=https://preview.your-domain.com

说明

• VITE_ORIGIN 保持 /api 即可，由 Nginx 反向代理转发到后端 9090 端口
• VITE_URL_CLOUD 可以留空
• VITE_PREVIEW_SERVICE_URL 为预览端部署地址，用于设计器的预览功能跳转

初始化 Library 静态资源

设计器运行时需要加载 @catpull/library 的构建产物（Vue、UniApp、Uni-Ui 等运行时依赖）。首次部署需要先编译并复制到设计器的 public 目录：

cd catpull-v3

# 自动检查并编译 library，复制到 designer/public/@catpull/library/
pnpm setup

该命令会：

• 检查 catpull-designer/public/@catpull/library/ 是否已存在
• 如不存在，自动编译 @catpull/library 包
• 将 packages/library/dist/ 复制到 catpull-designer/public/@catpull/library/

构建设计器

cd catpull-v3

# 构建前自动执行 setup
pnpm build:designer

构建产物输出到 catpull-designer/dist/ 目录。

Nginx 配置

将构建产物部署到 Nginx，并配置反向代理将 API 请求转发到主服务器：

server {
    listen 80;
    server_name your-domain.com;

    # 允许请求头包含下划线（CatPull 使用 app_id、app_platform 等下划线请求头）
    underscores_in_headers on;

    # 设计器静态资源
    root /var/www/catpull-designer/dist;
    index index.html;

    # 静态资源缓存
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Library 静态资源
    location /@catpull/library/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
        add_header Access-Control-Allow-Origin *;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:9090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 10m;
    }

    # SPA 路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }
}

HTTPS

生产环境强烈建议启用 HTTPS，可使用 Let's Encrypt 免费证书：

sudo certbot --nginx -d your-domain.com

常见问题

设计器加载依赖资源 404

检查 catpull-designer/dist/@catpull/library/ 目录是否存在且包含文件。

Monaco Editor 加载失败

构建产物中 editor/monaco-workers/ 目录必须完整。如果缺失，检查 vite.config.js 中 monacoEditorPlugin 配置是否正确。