MeterSphere源码编译指南：本地开发环境搭建步骤

引言

你是否在搭建MeterSphere本地开发环境时遇到各种难题？编译失败、依赖冲突、配置复杂？本文将带你一步到位，从环境准备到代码运行，全方位解决MeterSphere源码编译过程中的痛点，让你顺利搭建起高效的开发环境。读完本文，你将能够：

• 掌握MeterSphere源码编译的完整流程
• 解决常见的编译错误和环境配置问题
• 成功启动前后端服务并进行本地开发

环境准备

硬件要求

硬件	最低配置	推荐配置
CPU	4核	8核
内存	8GB	16GB
硬盘	100GB可用空间	200GB SSD

软件依赖

必装软件

软件	版本要求	说明
JDK	21+	MeterSphere后端基于Java 21开发
Maven	3.6+	用于构建后端项目
Node.js	18.0.0+	前端开发环境
pnpm	8.4.0	前端包管理工具
Git	2.30+	版本控制工具
MySQL	8.0+	数据库服务
Redis	6.0+	缓存服务

可选软件

• Docker: 用于容器化部署
• IDE: IntelliJ IDEA或VS Code（推荐）

源码获取

克隆代码仓库

git clone https://gitcode.com/gh_mirrors/me/metersphere.git
cd metersphere

查看项目结构

metersphere/
├── backend/           # 后端代码
├── frontend/          # 前端代码
├── pom.xml            # 项目根POM文件
└── README.md          # 项目说明文档

后端环境搭建

安装基础依赖

# 安装parent pom到本地仓库
./mvnw install -N

# 构建domain sdk
./mvnw clean install -DskipTests -DskipAntRunForJenkins --file backend/pom.xml

数据库配置

1. 创建数据库

CREATE DATABASE metersphere CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

2. 创建配置文件

# 创建配置文件目录
mkdir -p /opt/metersphere/conf

# 创建配置文件
cat > /opt/metersphere/conf/metersphere.properties << EOF
# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/metersphere?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&allowMultiQueries=true&nullCatalogMeansCurrent=true
spring.datasource.username=root
spring.datasource.password=password

# Redis配置
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.password=

# 服务器配置
server.port=8081

# 文件存储配置
metersphere.file-storage.type=local
metersphere.file-storage.local.path=/opt/metersphere/data
EOF

初始化数据库

MeterSphere启动时会自动执行数据库迁移脚本，无需手动执行SQL文件。

启动后端服务

# 进入后端目录
cd backend

# 使用Maven启动
./mvnw spring-boot:run -pl app

前端环境搭建

安装依赖

# 进入前端目录
cd frontend

# 安装依赖
pnpm install

配置开发环境

# 创建环境配置文件
cat > .env.development << EOF
VITE_APP_API_BASE_URL=http://localhost:8081/api
VITE_APP_PUBLIC_PATH=/
EOF

启动前端服务

# 开发模式启动
pnpm run dev

启动成功后，访问 http://localhost:5173 即可打开MeterSphere前端页面。

编译打包

后端打包

# 回到项目根目录
cd ..

# 打包后端
./mvnw clean package -DskipTests

打包后的文件位于 backend/app/target/metersphere-app.jar

前端打包

# 进入前端目录
cd frontend

# 打包前端
pnpm run build:local

打包后的静态文件位于 frontend/dist 目录

常见问题解决

后端启动失败

1. 端口占用问题

# 查看端口占用情况
netstat -tlnp | grep 8081

# 修改端口配置
sed -i 's/server.port=8081/server.port=8082/' /opt/metersphere/conf/metersphere.properties

2. 数据库连接失败

检查数据库服务是否启动，用户名密码是否正确。

前端依赖安装失败

1. 切换npm源

pnpm config set registry https://registry.npmmirror.com/

2. 清理缓存后重新安装

pnpm cache clean
pnpm install

开发工具配置

IntelliJ IDEA配置

1. 导入项目

• 选择 pom.xml 文件导入项目
• 等待Maven依赖下载完成

2. 配置JDK

• 打开 File > Project Structure
• 设置JDK版本为21

3. 配置运行参数

--spring.config.location=classpath:commons.properties,file:/opt/metersphere/conf/metersphere.properties

VS Code配置

1. 安装插件

• Vue Language Features (Volar)
• TypeScript Vue Plugin (Volar)
• Spring Boot Extension Pack

2. 配置启动项

创建 .vscode/launch.json 文件：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Application",
      "request": "launch",
      "mainClass": "io.metersphere.Application",
      "projectName": "app",
      "vmArgs": "--spring.config.location=classpath:commons.properties,file:/opt/metersphere/conf/metersphere.properties"
    }
  ]
}

开发流程

后端开发流程

1. 创建新的Controller

@RestController
@RequestMapping("/api/v1/example")
public class ExampleController {
    
    @GetMapping
    public Result<String> getExample() {
        return Result.success("Hello MeterSphere");
    }
}

2. 添加单元测试

@SpringBootTest
public class ExampleControllerTest {
    
    @Autowired
    private ExampleController exampleController;
    
    @Test
    public void testGetExample() {
        Result<String> result = exampleController.getExample();
        Assertions.assertEquals("Hello MeterSphere", result.getData());
    }
}

前端开发流程

1. 创建新组件

<template>
  <div class="example-component">
    {{ message }}
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const message = ref('Hello MeterSphere');
</script>

2. 添加路由

// src/router/routes/modules/example.ts
import { RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw = {
  path: '/example',
  name: 'Example',
  component: () => import('@/views/example/index.vue'),
};

export default routes;

参与贡献

1. 创建分支

git checkout -b feature/your-feature-name

2. 提交代码

git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

3. 创建Pull Request

访问GitCode仓库页面，创建新的Pull Request。

总结

通过本文档，你已经掌握了MeterSphere本地开发环境的搭建方法，包括环境准备、源码获取、前后端配置、编译打包等步骤。希望本文能帮助你顺利开展MeterSphere的开发工作。如有任何问题，欢迎在项目仓库提交issue或参与讨论。

相关资源

• MeterSphere官方文档
• Spring Boot文档
• Vue.js文档