前端部署技术文档

1. 项目概述

1.1 项目基本信息

项目名称	zs-arco-design-vue
技术栈	Vue 3 + TypeScript + Arco Design Vue
构建工具	Vite
部署方式	Docker + Nginx
环境要求	Node.js >= 18.0.0

1.2 核心依赖

依赖	版本	用途
Vue	^3.5.16	前端框架
TypeScript	^5.8.3	类型系统
Arco Design Vue	^2.57.0	UI 组件库
Vue Router	^4.5.1	路由管理
Pinia	^3.0.2	状态管理
Vite	^6.3.5	构建工具

2. 部署前准备

2.1 环境要求

环境	版本	说明
Node.js	>= 18.0.0	开发和构建环境
npm/yarn/pnpm	最新稳定版	包管理工具
Docker	>= 20.10.0	容器化部署
Nginx	>= 1.20.0	Web 服务器

2.2 依赖安装

bash

# 使用 npm 安装依赖
npm install

# 使用 yarn 安装依赖
yarn install

# 使用 pnpm 安装依赖
pnpm install

2.3 环境变量配置

项目使用 .env 文件管理环境变量，根据不同环境使用不同的配置文件：

文件名	环境	用途
`.env.development`	开发环境	开发环境配置
`.env.production`	生产环境	生产环境配置

生产环境配置示例：

env

VITE_API_BASE_URL=https://api.example.com

3. 构建流程

3.1 构建命令

项目提供了多种构建命令，用于不同的构建场景：

命令	说明	适用场景
`npm run dev`	启动开发服务器	开发阶段
`npm run build`	开发环境构建	测试阶段
`npm run build:prod`	生产环境构建	生产部署
`npm run report`	生成构建分析报告	性能优化
`npm run preview`	预览构建产物	构建验证

3.2 构建配置

生产环境构建配置位于 config/vite.config.prod.ts：

typescript

export default mergeConfig(
  {
    mode: 'production',
    plugins: [
      configCompressPlugin('gzip'),      // Gzip 压缩
      configVisualizerPlugin(),         // 构建分析
      configImageminPlugin(),           // 图片优化
    ],
    build: {
      sourcemap: true,                  // 生成 sourcemap
      rollupOptions: {
        output: {
          manualChunks: {               // 代码分割
            chart: ['echarts', 'vue-echarts'],
            vue: ['vue', 'vue-router', 'pinia', '@vueuse/core', 'vue-i18n'],
          },
        },
      },
      chunkSizeWarningLimit: 2000,      // 代码块大小警告阈值
    },
  },
  baseConfig,
);

3.3 构建产物

构建成功后，产物将生成在 dist 目录下，结构如下：

dist/
├── assets/            # 静态资源
│   ├── js/            # JavaScript 文件
│   ├── css/           # CSS 文件
│   └── img/           # 图片资源
├── index.html         # 入口 HTML 文件
└── vite.svg           # Vite 图标

4. 部署方式

4.1 传统部署

4.1.1 服务器准备

安装 Nginx
配置 Nginx 虚拟主机
上传构建产物到服务器

4.1.2 Nginx 配置

nginx

server {
    listen 80;
    server_name example.com;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html; 
    }

    location /api {
        proxy_pass https://api.example.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存配置
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}

4.1.3 部署步骤

构建项目：npm run build:prod
将 dist 目录下的所有文件上传到服务器指定目录
重启 Nginx 服务：systemctl restart nginx

4.2 Docker 部署

4.2.1 Dockerfile 说明

项目提供了 Dockerfile 用于容器化部署：

dockerfile

FROM registry.cn-beijing.aliyuncs.com/my-admin/zs-nginx:1.26.2

# 复制构建产物到 Nginx 静态目录
COPY ./dist /usr/share/nginx/html/

4.2.2 Nginx 配置文件 (zs-acro.conf)

nginx

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass https://demo.zsadmin.top/api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存配置
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}

4.2.3 Docker 部署步骤

构建项目：npm run build:prod
构建 Docker 镜像：

bash

docker build -t zs-arco-design-vue .

运行 Docker 容器：

bash

docker run -d -p 80:80 --name zs-arco-design-vue zs-arco-design-vue

验证部署：访问 http://localhost

4.3 容器编排 (Docker Compose)

4.3.1 docker-compose.yml 示例

yaml

version: '3.8'

services:
  frontend:
    build: .
    ports:
      - "80:80"
    restart: always
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./logs:/var/log/nginx
    networks:
      - zs-network

networks:
  zs-network:
    driver: bridge

4.3.2 部署步骤

构建项目：npm run build:prod
启动容器：docker-compose up -d
验证部署：访问 http://localhost

5. 持续集成与持续部署

5.1 CI/CD 流程

建议使用以下 CI/CD 流程：

代码提交：开发者将代码提交到 Git 仓库
自动构建：CI 工具自动构建项目并运行测试
代码检查：运行 ESLint、Stylelint 和 TypeScript 类型检查
构建产物上传：将构建产物上传到 artifact 仓库
自动部署：CD 工具将构建产物部署到测试或生产环境
部署验证：运行自动化测试验证部署结果

5.2 阿里云效 CI/CD 示例

阿里云效 CI/CD 配置通过流水线实现，以下是完整的配置示例：

在阿里云效控制台创建流水线
配置代码源：选择 Git 仓库，设置触发规则
添加构建任务：使用 Node.js 环境执行构建命令
添加部署任务：配置 SSH 部署到目标服务器

流水线配置示例（阿里云效 YAML 格式）

yaml

# 阿里云效流水线配置文件
sources:
  repo_0:
    type: codeup
    name: <REDACTED_PROJECT_NAME>
    endpoint: https://codeup.aliyun.com/<REDACTED_REPO_PATH>.git
    branch: dev
    triggerEvents:
    - push
    branchesFilter: ^dev$
    certificate:
      type: serviceConnection
      serviceConnection: <REDACTED_SERVICE_CONNECTION_ID>
defaultWorkspace: repo_0
stages:
  stage_0:
    name: 构建镜像
    jobs:
      job_0:
        name: 阿里云镜像构建
        runsOn:
          group: public/cn-beijing
        steps:
          step_0:
            name: Node.js 构建
            step: NodeBuild
            with:
              versionType: custom
              customNodeVersion: 20.19.0
              useCache: false
              nodeVersion: 20.19.0
              run: |-
                # input your command here
                # 在脚本开始处解码 PIPELINE_ID
                export PIPELINE_ID=$(echo "${PIPELINE_ID}" | base64 -d)
                export DATETIME=$(echo "${DATETIME}" | base64 -d)
                npm cache clean --force
                rm -rf node_modules
                rm -rf package-lock.json
                npm config delete registry
                npm config set registry https://registry.npmjs.org/
                npm install
                npm run build:prod
          step_1:
            name: 构建物上传
            step: ArtifactUpload
            with:
              artifact: <REDACTED_ARTIFACT_PREFIX>_${PIPELINE_ID}
              includePathInArtifact: true
              filePath:
              - dist/
              uploadType: flowPublic
              version: ${DATETIME}
          step_2:
            name: 镜像构建并推送至阿里云镜像仓库个人版
            step: ACRDockerBuild
            with:
              artifact: artifact
              variables: []
              dockerfilePath: Dockerfile
              noCache: false
              dockerRegistry: <REDACTED_IMAGE_REPO>
              dockerTag: latest
              region: cn-beijing
              serviceConnection: <REDACTED_SERVICE_CONNECTION_ID>
        driven: auto
        plugins: []
  stage_1:
    name: 部署
    jobs:
      job_0:
        name: Docker部署
        component: VMDockerDeploy
        driven: auto
        with:
          variables:
          - key: IMAGES_URL
            value: <REDACTED_IMAGE_REPO>:latest
          useEncode: true
          pauseStrategy: firstBatchPause
          machineGroup: <REDACTED_MACHINE_GROUP_ID>
          run: |-
            export IMAGES_URL=$(echo "${IMAGES_URL}" | base64 -d)
            export DATETIME=$(echo "${DATETIME}" | base64 -d)

            docker rm -f <REDACTED_CONTAINER_NAME>

            docker pull ${IMAGES_URL}

            docker run -d -p 8087:80 --name <REDACTED_CONTAINER_NAME> --restart always --network <REDACTED_NETWORK_NAME> ${IMAGES_URL}
            docker restart <REDACTED_NGINX_CONTAINER>
          executeUser: root
          batchNumber: 2
        plugins:
        - name: 钉钉机器人通知插件
          plugin: DingTalkPlugin
          triggerState:
          - fail
          - success
          with:
            noticeContent:
            - pipelineName
            - pipelineEnvironment
            - pipelineTag
            - pipelineRunRemark
            - triggerInfo
            - operator
            - pipelineJob
            - pipelineStage
            - status
            webhook: https://oapi.dingtalk.com/robot/send?access_token=<REDACTED_DINGTALK_ACCESS_TOKEN>
            customContent: 亲爱的主人
            secret: <REDACTED_DINGTALK_SIGN_SECRET>
        - name: 邮件通知插件
          plugin: EmailPlugin
          triggerState:
          - success
          with:
            email: <REDACTED_EMAIL>

阿里云效流水线配置步骤

登录阿里云效：进入阿里云效控制台
创建项目：选择「DevOps 项目」，填写项目信息
添加流水线：
- 进入项目，点击「流水线」→「创建流水线」
- 选择「自定义流水线」，点击「创建」
配置代码源：
- 选择「代码库类型」（Git 代码库）
- 选择对应的代码仓库和分支
- 设置触发规则：「推送到分支时触发」，选择 main 分支
配置构建阶段：
- 添加「Node.js 构建」步骤
- 配置 Node.js 版本为 18.x
- 构建命令：npm install && npm run lint && npm run type:check && npm run build:prod
配置部署阶段：
- 添加「SSH 部署」步骤
- 配置服务器信息（IP、端口、用户名）
- 选择认证方式（密码或 SSH 密钥）
- 配置源路径为 ./dist，目标路径为服务器上的部署目录
- 添加部署后命令（如重启 Nginx）
保存并运行：点击「保存并运行」，测试流水线是否正常工作

环境变量配置

在阿里云效流水线中配置以下环境变量：

变量名	描述	类型
REMOTE_HOST	服务器 IP 地址	加密
REMOTE_USER	服务器用户名	加密
REMOTE_PASSWORD	服务器密码（如果使用密码认证）	加密
SSH_PRIVATE_KEY	SSH 私钥（如果使用密钥认证）	加密
REMOTE_TARGET	服务器上的部署目录路径	普通

流水线触发规则

合并请求触发：当有合并请求提交到 main 分支时触发
定时触发：可设置每日/每周定时构建
手动触发：支持手动点击运行流水线

阿里云效 CI/CD 提供了完整的构建、测试、部署一体化解决方案，支持多环境部署、质量门禁、审批流程等高级功能，适合企业级项目使用。

6. 其他流水线

除了阿里云效，以下是其他常用的 CI/CD 流水线工具，您可以根据项目需求选择适合的工具：

工具名称	官方链接	特点
GitHub Actions	https://docs.github.com/zh/actions	与 GitHub 深度集成，配置简单，生态丰富
GitLab CI/CD	https://docs.gitlab.cn/jh/ci/	内置 GitLab 中，功能全面，支持自托管
Jenkins	https://www.jenkins.io/zh/	开源免费，插件丰富，高度可定制
CircleCI	https://circleci.com/docs/	配置简洁，性能优异，支持多种语言
Travis CI	https://docs.travis-ci.com/	专注开源项目，配置简单，使用广泛
Bitbucket Pipelines	https://bitbucket.org/product/zh-CN/features/pipelines	与 Bitbucket 集成，配置灵活，支持多种环境
TeamCity	https://www.jetbrains.com/teamcity/	JetBrains 出品，功能强大，易于使用
Azure DevOps	https://azure.microsoft.com/zh-cn/products/devops/	微软 Azure 生态，支持多种部署目标

6.1 选择建议

小型项目/开源项目：GitHub Actions、GitLab CI/CD、Travis CI
企业级项目：阿里云效、GitLab CI/CD、Jenkins、Azure DevOps
需要自托管：Jenkins、GitLab CI/CD
与云服务深度集成：阿里云效、GitHub Actions、Azure DevOps

每个 CI/CD 工具都有其特点和适用场景，建议根据项目规模、团队熟悉度和部署需求选择合适的工具。

前端部署技术文档 ​

1. 项目概述 ​

1.1 项目基本信息 ​

1.2 核心依赖 ​

2. 部署前准备 ​

2.1 环境要求 ​

2.2 依赖安装 ​

2.3 环境变量配置 ​

3. 构建流程 ​

3.1 构建命令 ​

3.2 构建配置 ​

3.3 构建产物 ​

4. 部署方式 ​

4.1 传统部署 ​

4.1.1 服务器准备 ​

4.1.2 Nginx 配置 ​

4.1.3 部署步骤 ​

4.2 Docker 部署 ​

4.2.1 Dockerfile 说明 ​

4.2.2 Nginx 配置文件 (zs-acro.conf) ​

4.2.3 Docker 部署步骤 ​

4.3 容器编排 (Docker Compose) ​

4.3.1 docker-compose.yml 示例 ​

4.3.2 部署步骤 ​

5. 持续集成与持续部署 ​

5.1 CI/CD 流程 ​

5.2 阿里云效 CI/CD 示例 ​

流水线配置示例（阿里云效 YAML 格式） ​

阿里云效流水线配置步骤 ​

环境变量配置 ​

流水线触发规则 ​

6. 其他流水线 ​

6.1 选择建议 ​

前端部署技术文档

1. 项目概述

1.1 项目基本信息

1.2 核心依赖

2. 部署前准备

2.1 环境要求

2.2 依赖安装

2.3 环境变量配置

3. 构建流程

3.1 构建命令

3.2 构建配置

3.3 构建产物

4. 部署方式

4.1 传统部署

4.1.1 服务器准备

4.1.2 Nginx 配置

4.1.3 部署步骤

4.2 Docker 部署

4.2.1 Dockerfile 说明

4.2.2 Nginx 配置文件 (zs-acro.conf)

4.2.3 Docker 部署步骤

4.3 容器编排 (Docker Compose)

4.3.1 docker-compose.yml 示例

4.3.2 部署步骤

5. 持续集成与持续部署

5.1 CI/CD 流程

5.2 阿里云效 CI/CD 示例

流水线配置示例（阿里云效 YAML 格式）

阿里云效流水线配置步骤

环境变量配置

流水线触发规则

6. 其他流水线

6.1 选择建议