Deployment Guide

Deployment Configuration

Basic Configuration

Before starting deployment, you need to fill in the following configuration items:

Configuration Item	Description	Example	Required
Project Name	Custom project name for identifying the deployment project	my-project	Yes
Project Preset Framework	Select the frontend framework used by the project	React, Vue, Angular	Yes
Node.js Version	Select the Node.js version to use for building	Node.js 18	Yes
Target Directory	The directory where the code to be built is located, default is root directory if left empty	/frontend	No

Build and Deployment Configuration

Configuration Item	Description	Example	Required
Install Command	Command to install project dependencies	npm install	Yes
Build Command	Command to compile and build the project	npm run build	Yes
Build Output Directory	Output directory after build completion	./dist	Yes
Deployment Path	Path to deploy to server, default is root path /	/ or /app	No

Configuration Notes

• Target Directory: If your frontend code is in a subdirectory of a monorepo project, you can specify the directory path
• Build Output Directory: Path relative to the project root directory or target directory, usually dist, build, etc.
• Deployment Path: Specifies the access path of the website on the server, defaults to a relative path generated by the project name, e.g., /my-project

Build Configuration

Supported Node.js Versions

The system supports the following Node.js versions:

• Node.js 16
• Node.js 18
• Node.js 20
• Node.js 22
• Node.js 24

Version Selection Recommendation

It is recommended to select the same Node.js version as your local development environment to avoid build issues caused by version differences.

Configuration Examples

React Project (Vite):

Project Name: my-react-app
Project Preset Framework: React
Node.js Version: Node.js 18
Target Directory: (leave empty)
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist
Deployment Path: /my-react-app

Vue Project (Vue CLI):

Project Name: my-vue-app
Project Preset Framework: Vue
Node.js Version: Node.js 18
Target Directory: (leave empty)
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist
Deployment Path: /my-vue-app

Advanced Configuration

Environment Variables

Supports configuring environment variables during build, commonly used to distinguish development/production environments:

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

Target Directory Description

The target directory is used to specify the location of the code to be built, suitable for the following scenarios:

1. Monorepo Project: Frontend code is in a subdirectory

   Target Directory: /packages/web

2. Multi-application Project: Project contains multiple applications

   Target Directory: /apps/admin

3. Independent Frontend Directory: Frontend code is in a separate folder

   Target Directory: /frontend

Note

If the project code is in the root directory, please leave the target directory empty or fill in /

Common Frontend Framework Deployment Configuration

React

Create React App

# Install command
npm install

# Build command
npm run build

# Build output directory
./build

package.json example:

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

Console configuration:

Project Preset Framework: React
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./build

Vite + React

# Install command
npm install

# Build command
npm run build

# Build output directory
./dist

vite.config.js configuration:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/', // 如果部署在子目录，需要修改此项
  build: {
    outDir: 'dist',
    assetsDir: 'assets'
  }
})

Console configuration:

Project Preset Framework: React
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist

Vue

Vue CLI (Vue 2/3)

# Install command
npm install

# Build command
npm run build

# Build output directory
./dist

vue.config.js configuration:

module.exports = {
  publicPath: '/', // 部署路径
  outputDir: 'dist',
  assetsDir: 'static',
  productionSourceMap: false
}

Console configuration:

Project Preset Framework: Vue
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist

Vite + Vue

# Install command
npm install

# Build command
npm run build

# Build output directory
./dist

vite.config.js configuration:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/',
  build: {
    outDir: 'dist'
  }
})

Console configuration:

Project Preset Framework: Vue
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist

Angular

# Install command
npm install

# Build command
npm run build

# Build output directory
./dist/项目名称

angular.json configuration:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "outputPath": "dist/your-project"
          }
        }
      }
    }
  }
}

Console configuration:

Project Preset Framework: Angular
Install Command: npm install
Build Command: npm run build
Build Output Directory: ./dist/your-project

Tip

Angular project output directories usually include the project name, please adjust according to your actual project configuration.

Build command

npm run build

Output directory

dist/项目名称

**angular.json configuration:**

```json
{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "outputPath": "dist/your-project"
          }
        }
      }
    }
  }
}

Tip

Angular project output directories usually include the project name, please adjust according to your actual project configuration.

Deployment Path Configuration

Root Path Deployment

If the website is deployed at the domain root path (such as https://example.com/), keep the deployment path at the default value /.

File Overwrite Risk Warning

Root path deployment will deploy build artifacts directly to the root directory / of static hosting, which means:

1. Existing files will be overwritten: Files in the root directory with the same name as build artifacts will be overwritten by newly deployed files
2. Multi-project conflicts: If multiple projects are deployed to the root path in the same static hosting environment, later deployed projects will overwrite previous project files
3. Cannot rollback individual files: Overwritten files cannot be automatically recovered

Recommended practices:

• If you need to deploy multiple projects in the same static hosting environment, assign independent sub-paths for each project (such as /app1, /app2)
• Before production environment deployment, it is recommended to verify in a test environment first
• Before deploying important projects, it is recommended to back up existing files first

Root Path Deployment Use Cases

Root path deployment is suitable for the following situations:

• Single application, exclusively occupying the entire static hosting environment
• Scenarios such as official websites, product homepages that require direct domain access
• Situations where it has been confirmed that there will be no conflicts with other projects

Sub-path Deployment

If the website is deployed at a sub-path (such as https://example.com/app/), you need to:

1. Configure in console: Set the deployment path to /app
2. Set base path in project configuration:

Vite Project

// vite.config.js
export default defineConfig({
  base: '/app/',
  // ... 其他配置
})

Vue CLI Project

// vue.config.js
module.exports = {
  publicPath: '/app/',
  // ... 其他配置
}

Create React App

// package.json
{
  "homepage": "/app"
}

Angular Project

// angular.json
{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "baseHref": "/app/"
          }
        }
      }
    }
  }
}

Note

The deployment path configuration must be consistent with base/publicPath/homepage in the project configuration file, otherwise it will cause resource loading failure.