支持地域：上海

部署指南

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

一、配置说明

1.1 基础配置

配置项	说明	示例	必填
项目名称	自定义项目标识	`my-project`	✅
项目框架	选择前端框架（支持自动识别并填充构建配置）	React、Vue.js、Angular、Next.js、Nuxt.js、VitePress、Astro、Hugo、Hexo、其他	✅
Node.js 版本	构建环境版本（16/18/20/22/24）	Node.js 18	✅

主流框架自动识别

「项目框架」下拉已支持 10 种主流前端框架：React、Vue.js、Angular、Next.js、Nuxt.js、VitePress、Astro、Hugo、Hexo，以及自定义配置（其他）。选择框架后，平台将自动推荐并填充对应的安装命令、构建命令和目标目录，减少手动配置成本，开发者无需手动配置构建参数即可一键部署。

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

Next.js（SSG 静态导出）

项目框架: Next.js
安装命令: npm install
构建命令: npm run build
构建产物目录: ./out
部署路径: /my-next-app

Nuxt（SSG 静态生成）

项目框架: Nuxt.js
安装命令: npm install
构建命令: npm run generate
构建产物目录: ./.output/public
部署路径: /my-nuxt-app

VitePress

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

Astro

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

Hugo

项目框架: Hugo
安装命令: (留空)
构建命令: hugo --minify
构建产物目录: ./public
部署路径: /my-hugo-site

Hexo

项目框架: Hexo
安装命令: npm install
构建命令: npx hexo generate
构建产物目录: ./public
部署路径: /my-blog

四、框架配置参考

React

Create React App

package.json：

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

Vite + React

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

vue.config.js：

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

Vite + Vue

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": "./" // 子路径部署使用相对路径
          }
        }
      }
    }
  }
}

Next.js

静态网站托管支持部署 SSG（静态站点生成） 模式的 Next.js 应用，推荐使用官方的 Nextjs Web 应用模板快速创建项目，已内置 CloudBase SDK 集成。

next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 启用静态导出
  images: {
    unoptimized: true // 静态导出需关闭图片优化
  },
  basePath: '', // 子路径部署时填写，如 '/my-app'
  trailingSlash: true
}

module.exports = nextConfig

package.json：

{
  "scripts": {
    "build": "next build"
  }
}

Nuxt

静态网站托管支持部署 SSG（静态站点生成） 模式的 Nuxt 应用，推荐使用官方的 Nuxt Web 应用模板快速创建项目，已内置 CloudBase SDK 集成。

构建产物目录：./.output/public

nuxt.config.ts：

export default defineNuxtConfig({
  ssr: false, // 或使用 nitro.preset: 'static'
  app: {
    baseURL: '/', // 子路径部署时填写，如 '/my-app/'
    buildAssetsDir: '/_nuxt/'
  }
})

package.json：

{
  "scripts": {
    "generate": "nuxt generate"
  }
}

VitePress

构建产物目录：./docs/.vitepress/dist

docs/.vitepress/config.js：

export default {
  base: '/', // 子路径部署使用 '/my-docs/'
  outDir: '.vitepress/dist'
}

Astro

astro.config.mjs：

import { defineConfig } from 'astro/config'

export default defineConfig({
  base: '/', // 子路径部署填写，如 '/my-astro-site'
  output: 'static'
})

Hugo

构建产物目录：./public

hugo.toml（或 config.toml）：

baseURL = "https://example.com/"
# 子路径部署：baseURL = "https://example.com/my-site/"
publishDir = "public"

构建命令：hugo --minify

Hexo

构建产物目录：./public

_config.yml：

url: https://example.com
root: / # 子路径部署填写 '/my-blog/'
public_dir: public

构建命令：npx hexo generate

五、部署路径配置

根路径部署（`/`）

适用场景：

单一应用，独占整个静态托管环境
官网、产品主页等需要域名直接访问
访问地址：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: 建议选择与本地开发环境相同的版本，避免构建差异

一、配置说明​

1.1 基础配置​

1.2 构建配置​

1.3 环境变量（可选）​

二、部署日志展示​

日志示例​

成功部署日志​

如何判断部署是否成功​

三、快速配置示例​

纯静态项目​

React (Vite)​

Vue (Vue CLI)​

Angular​

Next.js（SSG 静态导出）​

Nuxt（SSG 静态生成）​

VitePress​

Astro​

Hugo​

Hexo​

四、框架配置参考​

React​

Create React App​

Vite + React​

Vue​

Vue CLI​

Vite + Vue​

Angular​

Next.js​

Nuxt​

VitePress​

Astro​

Hugo​

Hexo​

五、部署路径配置​

根路径部署（/）​

子路径部署（/app）​

六、特殊场景配置​

Monorepo 项目​

多应用项目​

常见问题​

Q: 部署后静态资源 404？​

Q: 如何部署多个项目？​

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

一、配置说明

1.1 基础配置

1.2 构建配置

1.3 环境变量（可选）

二、部署日志展示

日志示例

成功部署日志

如何判断部署是否成功

三、快速配置示例

纯静态项目

React (Vite)

Vue (Vue CLI)

Angular

Next.js（SSG 静态导出）

Nuxt（SSG 静态生成）

VitePress

Astro

Hugo

Hexo

四、框架配置参考

React

Create React App

Vite + React

Vue

Vue CLI

Vite + Vue

Angular

Next.js

Nuxt

VitePress

Astro

Hugo

Hexo

五、部署路径配置

根路径部署（`/`）

子路径部署（`/app`）

六、特殊场景配置

Monorepo 项目

多应用项目

常见问题

Q: 部署后静态资源 404？

Q: 如何部署多个项目？

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