部署指南

本指南介绍如何配置和部署前端项目到云开发静态托管服务。

一、配置说明

1.1 基础配置

配置项	说明	示例	必填
项目名称	自定义项目标识	my-project	✅
项目框架	选择前端框架	React、Vue、Angular、其他	✅
Node.js 版本	构建环境版本（16/18/20/22/24）	Node.js 18	✅

1.2 构建配置

配置项	说明	示例	必填
目标目录	代码所在目录（默认根目录）	/frontend	-
安装命令	安装依赖	npm install	静态项目可留空
构建命令	编译构建	npm run build	静态项目可留空
构建产物目录	输出目录	./dist、./build	✅
部署路径	访问路径	/、/app	-

纯静态项目部署

如果项目是纯 HTML/CSS/JS 文件，无需构建：

• 安装命令和构建命令留空
• 构建产物目录填写静态文件所在目录（如 .、./public）
• 详细说明请参考：纯静态项目部署

1.3 环境变量（可选）

支持配置构建时的环境变量：

NODE_ENV=production
VITE_API_URL=https://api.example.com
REACT_APP_ENV=production

---

二、部署日志展示

配置提交后,系统会执行构建和部署流程,您可以在控制台查看实时日志:

日志示例

成功部署日志

Deployment complete 👉 https://lowcode-0gwpl9v4xxxxxxx-1258057692.tcloudbaseapp.com
✔ Total files: 4
✔ Successfully uploaded 4 file(s)
┌────────┬─────────────────────────────────────┐
│ Status │ File │
├────────┼─────────────────────────────────────┤
│ ✔ │ /cosdesign/cosdesign.code-workspace │
├────────┼─────────────────────────────────────┤
│ ✔ │ /cosdesign/index.html │
├────────┼─────────────────────────────────────┤
│ ✔ │ /cosdesign/script.js │
├────────┼─────────────────────────────────────┤
│ ✔ │ /cosdesign/style.css │
└────────┴─────────────────────────────────────┘
✖ Failed to upload 0 file(s)
[2026-01-27 20:03:33] 自定义部署完成
Finished, code: 0, duration: 6.9s

如何判断部署是否成功

看到以下关键信息即表示部署成功：

成功标志

✅ ✔ Successfully uploaded X file(s) - 文件上传成功数量
✅ Deployment complete 👉 访问地址 - 部署完成并显示访问链接
✅ Finished, code: 0 - 进程退出码为 0（表示无错误）
✅ 文件列表中所有文件状态都是 ✔ - 所有文件上传成功

失败标志

如果看到以下信息，说明部署失败或部分失败：

• ❌ ✖ Failed to upload X file(s) 且 X > 0 - 有文件上传失败
• ❌ Finished, code: 1 或其他非 0 值 - 构建或部署过程出错
• ❌ 日志中出现 Error: 或 Failed: 等错误提示

---

三、快速配置示例

纯静态项目

项目框架: 其他
安装命令: (留空)
构建命令: (留空)
构建产物目录: .
部署路径: /my-static-site

React (Vite)

项目框架: React
安装命令: npm install
构建命令: npm run build
构建产物目录: ./dist
部署路径: /my-react-app

Vue (Vue CLI)

项目框架: Vue
安装命令: npm install
构建命令: npm run build
构建产物目录: ./dist
部署路径: /my-vue-app

Angular

项目框架: Angular
安装命令: npm install
构建命令: npm run build
构建产物目录: ./dist/项目名称
部署路径: /my-angular-app

---

四、框架配置参考

React

Create React App

• 构建产物目录：./build
• package.json：

  {
    "scripts": {
      "build": "react-scripts build"
    }
  }

Vite + React

• 构建产物目录：./dist

• vite.config.js：

  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'
  
  export default defineConfig({
    plugins: [react()],
    base: './', // 子路径部署使用相对路径
    build: {
      outDir: 'dist'
    }
  })

Vue

Vue CLI

• 构建产物目录：./dist
• vue.config.js：

  module.exports = {
    publicPath: './', // 子路径部署使用相对路径
    outputDir: 'dist'
  }

Vite + Vue

• 构建产物目录：./dist

• vite.config.js：

  import { defineConfig } from 'vite'
  import vue from '@vitejs/plugin-vue'
  
  export default defineConfig({
    plugins: [vue()],
    base: './', // 子路径部署使用相对路径
    build: {
      outDir: 'dist'
    }
  })

Angular

• 构建产物目录：./dist/项目名称
• angular.json：

  {
    "projects": {
      "your-project": {
        "architect": {
          "build": {
            "options": {
              "outputPath": "dist/your-project",
              "baseHref": "./" // 子路径部署使用相对路径
            }
          }
        }
      }
    }
  }

---

五、部署路径配置

根路径部署（/）

适用场景：

• 单一应用，独占整个静态托管环境
• 官网、产品主页等需要域名直接访问
• 访问地址：https://example.com/

注意事项

根路径部署会覆盖静态托管根目录下的现有文件：

• 同名文件会被覆盖且无法自动恢复
• 多个项目部署到根路径会互相覆盖
• 建议：多项目场景使用子路径（如 /app1、/app2）

子路径部署（/app）

适用场景：

• 同一环境部署多个项目
• 需要隔离不同应用的文件
• 访问地址：https://example.com/app/

配置要求：

在项目配置中将公共路径设置为相对路径 ./ ，避免静态资源加载失败。

框架	配置文件	配置项
Vite	vite.config.js	base: './'
Vue CLI	vue.config.js	publicPath: './'
Create React App	package.json	"homepage": "./"
Angular	angular.json	"baseHref": "./"

---

六、特殊场景配置

Monorepo 项目

前端代码在子目录中：

目标目录: /packages/web
安装命令: npm install
构建命令: npm run build
构建产物目录: ./dist

多应用项目

项目包含多个应用：

目标目录: /apps/admin
安装命令: npm install
构建命令: npm run build
构建产物目录: ./dist

---

常见问题

Q: 部署后静态资源 404？

A: 检查是否配置了正确的 base/publicPath，子路径部署需要使用相对路径 ./

Q: 如何部署多个项目？

A: 为每个项目配置不同的部署路径，如 /app1、/app2，避免文件冲突

Q: Node.js 版本如何选择？

A: 建议选择与本地开发环境相同的版本，避免构建差异