Git基础与开发平台搭建

Git

基础

创建分支，git branch 新分支名：在 当前提交 （即 HEAD 指向的分支名所在的那个提交）上，创建一个新的 新分支名。
切换分支，git checkout 目标分支名：将 HEAD 移动，使其指向 目标分支名。
提交，git commit：基于 当前提交 ，创建一个新提交（圆圈），并让 HEAD 指向的 分支名 移动并指向这个新提交。
合并分支，git merge 目标分支名：将 目标分支名 所在的提交与 当前提交 合并，创建下一条新的 提交（圆圈） ，并让 HEAD 指向的 分支名 移动并指向这个新提交。
变基，git rebase 目标分支名：将 HEAD 指向的 分支名 及其所在的提交（圆圈），转而连接到 目标分支名 所在的提交后面。

"HEAD 指向" 即*标注

远程

"远程"就是指存放在公司服务器（比如 GitLab）上的那个中心仓库。你和同事都要把自己的提交传到那里，或者从那里拉取别人的提交。

我们先引入两个关于远程的新概念：

远程仓库名 ：通常默认叫 origin，它是服务器网址的"快捷标签"。
远程分支名 ：通常叫 origin/main，它是本地用来记录 "服务器上的 main 分支名 当前指向哪个提交 " 的只读标签。

工作中最常用的 4 个远程命令（用统一指代词解释）：

下载整个项目：git clone 网址

把服务器上的所有提交（圆圈）和分支名 下载到本地。同时自动给服务器网址贴上远程仓库名 origin 的标签。

（这是第一次拿到项目代码时做的第一件事。）
获取同事的最新进度：git fetch 远程仓库名

去服务器检查有没有新的提交。如果有，下载下来，并更新本地的远程分支名 （如 origin/main），让它指向服务器上的最新提交。

（ fetch 只是下载和更新只读标签，不会改变你的当前提交，非常安全。）
拉取并合并同事的代码：git pull 远程仓库名远程分支名

它是 git fetch 和 git merge 的结合体。把服务器上的新提交下载下来，合并分支，生成下一条全新提交，并让本地分支名（及其HEAD）移动，指向这个新生成的提交。

（通俗说：同事写了新代码推到服务器了，你每天上班第一件事就是 pull 下来，和你的代码合并。）

解冲突：合并时揉合代码，如果你们俩碰巧改了同一个文件的同一行代码，Git 就懵了，会提示"冲突"，需要手动决定保留谁的，即"解冲突"
上传你的代码给同事：git push 远程仓库名本地分支名

把你本地的分支名 上的新提交上传到服务器，并让服务器上的同名分支名 移动指向这些新提交。

（通俗说：你写完代码，测试没问题了，push 到服务器上，同事就能看到你的代码了。）

前后端项目本地环境搭建与启动

本文按真实执行先后顺序整理

全流程导览

阶段一：环境自检 --- 验证本地 JDK 17+ 与 Node.js 18+ 环境。
阶段二：代码检出 (Git Clone) --- 拉取前后端两个项目仓库。
阶段三：后端项目准备 (IDEA) --- 依次完成以下准备：
1. 配置 Maven 私服 settings.xml。
2. 向公司获取中间件连接信息（MySQL/Redis/Nacos）。
3. Navicat 建库并导入 SQL 脚本（含多数据源 gr_wms_* 库）。
4. Nacos 建专属 Namespace 并克隆、修改 IP 配置。
5. 修改本地 bootstrap.yml（密码加引号、填 Namespace ID）。
6. IDEA 配置 VM 参数及 Shorten 命令行。
7. 按顺序启动微服务（Gateway → Compose 聚合）。
阶段四：前端项目启动与联调 (Vue3) --- 依次完成以下准备：
1. 配置 npm 私服 registry。
2. 使用 npm install --legacy-peer-deps 安装依赖。
3. 放行 esbuild/core-js 脚本。
4. 修改 .env.development 代理指向 localhost:30000。
5. 执行 npm run dev 启动项目。
完成 --- ✅ 前后端联调成功。

启动顺序：基础设施（远程 Nacos/MySQL/Redis）就绪 ➜ 后端服务（网关和业务，顺序随意） ➜ 前端项目

阶段一：本地环境自检

在开始拉取代码前，必须确保本地的运行环境满足项目要求。打开命令行终端

1. 验证后端 JDK (要求 17+)

bash 复制代码

java -version

达标：输出包含 "17.x.x" 或更高版本（如 21）。
不达标：需前往 Oracle 或 Adoptium 官网下载 JDK 17/21 安装包并配置环境变量。

2. 验证前端 Node.js (要求 18+)

bash 复制代码

node -v

达标：输出 v18.x.x 或更高版本（如 v20, v24）。
不达标/未安装 ：前往 Node.js 官网下载页，选中 LTS (长期支持版) （默认），点击 Windows Installer (.msi)（这是node-v24.18.0-x64下载链接）下载安装包，一路 Next 安装。

注意：Node.js 安装完成后，必须关闭当前 cmd 窗口重新打开 ，环境变量才会生效。重新打开后再执行 node -v 确认。

阶段二：代码检出（Git Clone）

1. 建立工作目录

建议在非系统盘（如 D 盘）创建专门文件夹，例如 D:\work_code。

2. 拉取前后端项目

在 D:\work_code 文件夹顶部路径栏清空内容、输入 cmd 回车，可直接定位到该目录的命令行：

bash 复制代码

# 拉取后端（Spring Cloud 微服务）
git clone https://gitlab.xxx.com/xxx/jkkj-java-cloud.git
# 拉取前端（Vue3 + Vite）
git clone https://gitlab.xxx.com/xxx/jkkj-base-template-vue3.git

预期结果：

只要后续出现 Receiving objects: 100% 即代表成功。

D:\work_code 文件夹新增两个文件夹jkkj-java-cloud、jkkj-base-template-vue3 （所拉取链接对应的名字）。

若提示输入密码，输入 GitLab 账号密码（如果输入密码时屏幕不显示字符，盲打完回车即可）。

阶段三：后端项目准备（IDEA + Spring Cloud）

1. 配置 Maven 私服（让 IDEA 能下载公司依赖）

一、找到 Maven 的配置文件路径

在 IDEA 顶部菜单栏，点击 File -> Settings
在左侧菜单依次展开：Build, Execution, Deployment -> Build Tools -> Maven。
看右侧的 User settings file（用户配置文件）这一行。
它后面通常会显示一个路径，比如：C:\Users\32804.m2\settings.xml。
重点：勾选它后面的 Override（覆盖）复选框。
记住这个路径 ，我们等下要去修改这个文件。点击右下角的 Apply，先别关窗口。

二、修改配置文件，接入公司私服

打开电脑的"文件资源管理器"，找到刚才那个路径（比如进入 C:\Users\32804\.m2 文件夹）。
看看里面有没有一个叫 settings.xml 的文件。
- 如果有：右键 -> 打开方式 -> 选择"记事本"。
- 如果没有 ：在空白处右键 -> 新建 -> 文本文档，命名为 settings.xml（改后缀），然后用记事本打开。
把里面的内容全部清空 ，然后复制并粘贴下面这段配置代码模版（已经把maven私服地址写进去了，填写账号密码）：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <!-- 私服认证：id 必须与下方 mirror 的 id 完全一致 -->
    <servers>
        <server>
            <id>company-nexus</id>
            <username>Maven私服账号</username>
            <password>Maven私服密码</password>
        </server>
    </servers>

    <!-- 镜像：拦截所有仓库请求，统一走公司私服 -->
    <mirrors>
        <mirror>
            <id>company-nexus</id>
            <mirrorOf>*</mirrorOf>
            <name>Company Internal Nexus</name>
            <url>Maven私服地址</url>
        </mirror>
    </mirrors>
</settings>

保存并关闭记事本。
回到 IDEA 的 Settings 窗口，点击 OK 保存设置。

三、让 IDEA 开始下载后端依赖

在 IDEA 中，点击 File -> Open ，选择之前克隆下来的后端项目文件夹 D:\work_code\jkkj-java-cloud，点击 OK 打开。
IDEA 打开后，右下角会弹出一个进度条，显示 Downloading... 或者 Syncing...。
请耐心等待 ！因为微服务项目非常庞大，第一次下载所有的"零件"（Jar包）可能需要 10 到 30 分钟，取决于网速。

2. 索要中间件连接信息

微服务依赖 MySQL / Redis / Nacos 。建议不要本地安装这三个软件（极度占用内存、配置繁琐），直接复用公司公共测试环境。

3. 导入数据库脚本（Navicat）

第一步：用 Navicat 连接 MySQL，建立你的专属数据库

根据后端 README 文档的要求，项目启动需要 4 个数据库。我们要去服务器上把它们建好，并导入初始数据。

打开 Navicat Premium 17，点击左上角的 "连接" -> "MySQL"。
填写连接信息：
- 连接名：随便起，比如 jkkj-MySQL
- 主机：远程MySQL IP
- 端口：3306
- 用户名：远程MySQL 账号
- 密码：远程MySQL 密码
点击左下角的 "测试连接" ，如果显示 "连接成功"，点击 "确定" 保存。
新建数据库 （建库规范 ：统一字符集 utf8mb4，排序规则 utf8mb4_general_ci。）：使用 Navicat 连接远程测试服 MySQL，按以下规范建立专属数据库：
1. 建库清单与导入顺序 （以专属后缀 _junjie 为例）：
- 主库 (系统底座) ：新建 gr_wms_sys_server_junjie。导入 jnpf dbnull init.sql (纯净底座)
- 业务库 (WMS 数据) ：新建 gr_wms_server_junjie。
  - 说明：低代码平台的业务表是动态生成的，此库只需建空库，无需导入任何 SQL 脚本。
- (可选) 调度库 ：新建 gr_wms_xxjob_junjie，导入 jnpf xxljob init.sql。
- (可选) 流程库 ：新建 gr_wms_flow_junjie，导入 jnpf flow init.sql。

4. Nacos 控制台配置（专属 Namespace + 改 IP）

打开浏览器 ，访问提供的nacos网址： 公司内网 Nacos 地址
登录：账号 nacos账号，密码 nacos密码。
新建命名空间 ：
- 点击左部菜单栏的 "命名空间" 。
- 点击 "新建命名空间" 。
- 命名空间 ID ：必须填 自定义英文 ID ，便于 bootstrap 引用（如：Junjie-dev）。
- 命名空间名称：随意填。
- 点击确定。
克隆（复制）配置 ：
- 点击左部菜单的 "配置管理" -> "配置列表" 。
- 在页面左上角，点击 test 命名空间（这时候下面会列出 test 里的所有配置）。
- 选中所有配置，目标命名空间 ，点击下面的 "克隆" 按钮，选择你刚才新建的 命名空间 ID，点击 "开始克隆" 。 (这样，就拥有了一套和 test 一模一样，但完全属于自己的配置文件了！)

5.修改配置文件

以下是你重新克隆后，唯一需要修改的 3 个具体修改点 。除了这 4 处，其他所有配置一律保持原样，绝对不要动。

datasource.yaml是核心连接配置，必须指向你的专属隔离环境：

配置项	原值（test 空间）	改为（你的 Junjie-dev 空间）
`spring.data.redis.database`	`4`	`5`(或其他不相同的)
`spring.datasource.db-name`	`gr_wms_sys_server`	在 Navicat 里建的专属主库名
`spring.datasource.dynamic.datasource.gr_wms_server.url`	`jdbc:mysql://原IP:3306/gr_wms_server?...`	IP、库名都要改，指向你的专属业务数据库

6. 修改本地 bootstrap.yml（连接 Nacos）

因为后端可以只启动JkkjComposeExampleApplication和网关JkkjGatewayApplication。 JkkjCompose把其他的服务都纳进去了

所以，在idea中，修改微服务 Jkkj-Compose-Example 和网关 Jkkj-Gateway 目录下的 bootstrap.yml 或 bootstrap-dev.yml，替换为测试服真实数据。

yaml 复制代码

spring:
  cloud:
    nacos:
      username: nacos
      password: 'nacos密码'   # ⚠️ 必须加单引号，含 + 等特殊字符
      discovery:
        server-addr: ${spring.cloud.nacos.config.server-addr}
        namespace: ${spring.cloud.nacos.config.namespace}
      config:
        # Nacos 配置中心的服务器地址，在Nacos网址中找到，这样的 . . . : 
        server-addr: 公司内网 Nacos 地址
        # 填写 Nacos 【命名空间】列表里自己的 "命名空间 ID"
        namespace: 'Junjie-dev'
        file-extension: yaml

⚠️ 两大隐蔽坑：

密码特殊字符 ：密码含 +、@、! 等必须用单引号 包裹，否则 YAML 解析错误导致 403 user not found。

Namespace 必须填 ID ：namespace 绝不能填中文名称，必须填 Nacos 网页端生成的命名空间 ID（本项目为 Junjie-dev）。

7. 调试配置

操作：Edit Configurations → 先后选中JkkjComposeExampleApplication、JnpfGatewayApplication，都对其进行后面操作 → 点击修改选项 → 勾选添加虚拟机选项、缩短命令行 →

1. IDEA 全局配置优化（防命令行过长）

把 Shorten command line（缩短命令行）改为 @argfile (Java 9+)。

微服务依赖极多，Windows 下直接启动会报 Command line is too long。

2. JDK 17 必备 VM 参数（防反射崩溃）

虚拟机选项输入框，粘贴：

text 复制代码

--add-opens=java.base/java.lang=ALL-UNNAMED
--add-opens=java.base/java.lang.reflect=ALL-UNNAMED
--add-opens=java.base/java.lang.invoke=ALL-UNNAMED
--add-opens=java.base/java.math=ALL-UNNAMED
--add-opens=java.base/sun.net.util=ALL-UNNAMED
--add-opens=java.base/java.io=ALL-UNNAMED
--add-opens=java.base/java.net=ALL-UNNAMED
--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/java.security=ALL-UNNAMED
--add-opens=java.base/java.text=ALL-UNNAMED
--add-opens=java.base/java.time=ALL-UNNAMED
--add-opens=java.base/java.util=ALL-UNNAMED
--add-opens=java.base/jdk.internal.module=ALL-UNNAMED
--add-opens=java.base/sun.security.util=ALL-UNNAMED

项目底层使用大量旧版反射机制，JDK 9+ 加强了模块化封装，JDK 17 默认禁止反射访问内部 API。

8. Compose 聚合模块启动法

本地只需启动两个模块：

jkkj-gateway（网关，端口 30000）
jkkj-compose-example（大杂烩聚合模块，把核心业务打包到一起）

9. 按顺序启动微服务

一般启动顺序：

确认基础设施：Nacos / MySQL / Redis 正常运行（Navicat、Nacos 网页可访问）。
网关：jkkj-gateway。
聚合业务 ：jkkj-compose-example（带 @EnableFileStorage）。
✅ 启动成功标志 ：控制台输出 Started JkkjComposeExampleApplication in X.XX seconds

阶段四：前端项目启动与联调（Vue3 + Vite）

在前端项目目录下快速唤起命令提示符窗口，以下命令在这里执行

在本地文件资源管理器中，打开前端项目根目录 jkkj-base-template-vue3。
快速打开终端：在文件夹顶部的地址栏中，清空当前路径，输入 cmd 并按下回车键。 (注：也可直接在 IDEA / VS Code 等 IDE 中打开该项目，并使用内置的 Terminal 终端)
启动前端服务：在打开的终端中，执行以下命令启动前端开发服务器：

1. 配置公司 npm 私服（解决 404 找不到内部包）

公司内部 UI 组件库（如 jkkj-ui）不在公网，必须配置私服地址。

前提：

已连公司内网或 VPN。
获取到公司的私有 npm 仓库地址

在前端项目根目录（D:\work_code\jkkj-base-template-vue3）新建一个名为 .npmrc 的文件。在文件中写入以下内容并保存：

registry=npm私服地址

2. 安装依赖（解决版本冲突）

npm v7+ 对 peerDependencies 版本冲突严格校验，公司旧项目极易触发 ERESOLVE。必须加"忽略冲突"参数：

css 复制代码

npm install --legacy-peer-deps

预期结果 ：

末尾输出 added N packages in Xs/m，无 ERESOLVE 报错，生成 node_modules 与 package-lock.json。弃用/引擎警告可无视。
若加 --legacy-peer-deps 后仍报 ERESOLVE，可删除已生成的 package-lock.json 后重试：
css 复制代码
del package-lock.json
npm install --legacy-peer-deps
这是处理"锁文件锁定了冲突版本"的常见兜底手段

3. 放行底层脚本（仅当上一步出现拦截提示时）

若第 2 步未出现该警告，本步直接跳过。

若第 2 步结尾出现类似

perl 复制代码

npm warn allow-scripts 4 packages have install scripts not yet covered by allowScripts:
npm warn allow-scripts   esbuild@0.11.23 (postinstall: node install.js)
npm warn allow-scripts   core-js@3.49.0 (postinstall: node -e "try{require('./postinstall')}catch(e){}")
npm warn allow-scripts   esbuild@0.28.1 (postinstall: node install.js)
npm warn allow-scripts   esbuild@0.25.12 (postinstall: node install.js)

这是npm 的 allow-scripts 机制 在提醒：项目中有 4 个包包含了 安装后脚本（postinstall），但目前还没有被明确批准执行。
涉及的包：esbuild（三个不同版本：0.11.23、0.28.1、0.25.12）、core-js@3.49.0

npm v12 或 pnpm v10+ 默认拦截 install 脚本，需手动放行并补跑，依次执行：

python 复制代码

npm approve-scripts esbuild          # 按包名批准(覆盖该包所有已安装版本)
npm approve-scripts core-js
# 或者一次性批量批准所有待审核脚本:
npm approve-scripts --allow-scripts-pending
# 也可以用 --all 批准全部:
npm approve-scripts --all

npm install --legacy-peer-deps       # 再次执行,补跑被放行的脚本

预期结果 ：

再次安装时不再出现上述警告，正常执行完毕。

4. 配置本地代理（解决跨域与 404）

前端请求后端接口时，若直接请求前端端口会报 404。修改本地文件D:\work_code\jkkj-base-template-vue3\.env.development，将代理指向本地网关 30000 端口：

properties 复制代码

# 注意去掉末尾斜杠
VITE_PROXY = [["/dev","http://localhost:30000"], ["/reportDev","http://localhost:30000"]]

⚠️ 修改 .env 后必须重启前端服务 （在前端操作命令行，Ctrl+C → 重新 npm run dev）才能生效。

5. 启动项目

bash 复制代码

npm run dev
# 或 npm run serve（看 package.json 的 scripts）

打开项目的 "D:\work_code\jkkj-base-template-vue3\package.json"，看 scripts 里面有没有 dev 或者 serve：

如果看到 "dev": "vite"，就执行 npm run dev。

如果只有 "serve": "vite"，就执行 npm run serve 。
（大多数 Vue3 + Vite 项目默认都是 npm run dev）

预期结果：

等待时间稍长，只要最后出现 VITE v.x.x ready in xxx ms 和 Local: http://localhost:xxxx/，按住 Ctrl 点击链接即可访问。