Maven on Liangweidong's blog

Nexus Repository 私服：Maven / Nuget / Docker 仓库与第三方包上传实战

Sun, 15 Dec 2024 00:00:00 +0800

Sonatype Nexus Repository 3 是企业里最常见的制品库——既可以代理 Maven Central、npm、Docker Hub，也可以做内部 hosted 仓库托管私有 jar / docker 镜像，还可以把多个仓库组合成"仓库组"对外暴露。这篇文章把 Nexus 3 的部署、仓库创建、maven 镜像、Docker 仓库、第三方 jar 上传实战一次性收齐。

阅读对象：需要搭建企业 Maven 私服的 Java 团队；需要私有 Docker Registry；需要上传第三方包（公司内部 SDK）的开发。 覆盖范围：Sonatype Nexus 3 部署（启动慢要 12 分钟）、maven 仓库 4 种类型（proxy/hosted/group）、maven settings.xml 镜像配置、Docker 仓库（hosted + Bearer Token）、第三方 jar 上传（mvn deploy:deploy-file）、Blob 清理（Compact blob store）。

一、Nexus 在企业里的角色

角色	价值
代理公共仓库	Maven Central 镜像、npm 镜像、PyPI 镜像
托管内部 jar	公司内部 SDK / 框架
托管第三方 jar	没上传到 Maven Central 的商业 SDK
私有 Docker Registry	docker push/pull 内部镜像
仓库组（group）	把多个仓库合并，settings.xml 配一个 URL
权限 / 审计	RBAC、操作审计、清理策略

二、Nexus 3 部署

2.1 拉取与启动

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


docker pull sonatype/nexus3
docker pull sonatype/nexus3:3.72.0-java17-ubi # 生产推荐

mkdir -p /home/docker/nexus/data
chown -R 200 /home/docker/nexus/data # Nexus 进程以 UID 200 跑

docker run -d --restart=always --name nexus \
 -p 8081:8081 \
 -p 8082:8082 \
 -v /home/docker/nexus/data:/nexus-data \
 sonatype/nexus3

关键：

端口 8081 = Web UI

端口 8082 = Docker Registry（V2 API）

目录 /nexus-data 持久化（必须可写，UID 200）

首次启动要 12 分钟（拉取 + 初始化）

2.2 JVM 调优（生产必加）

1
2
3
4
5
6


docker run -d --restart=always --name nexus \
 -p 8081:8081 \
 -p 8082:8082 \
 -v /home/docker/nexus/data:/nexus-data \
 -e INSTALL4J_ADD_VM_PARAMS="-Xms2703m -Xmx2703m -XX:MaxDirectMemorySize=2703m -Djava.util.prefs.userRoot=/nexus-data" \
 sonatype/nexus3

Why 2703m？ Nexus 推荐 4GB JVM 堆（-Xms = -Xmx = 2.7GB，留 1.3GB 给 OS + MetaSpace）。

2.3 首次登录

1
2
3


# 等启动完成（看日志）
docker logs -f --tail=100 nexus
# 输出：Started Sonatype Nexus OSS 3.37.3-02

访问 http://<host>:8081
用户名 admin
密码在 /home/docker/nexus/data/admin.password

1
2


cat /home/docker/nexus/data/admin.password
# 形如：b52798ef-123d-4f46-9e84-416da2fa4bf8

登录后强制改密码
关闭匿名访问（“Settings → Security → Anonymous Access” 设为 disabled）

2.4 启动失败排错

症状：org.apache.http.conn.ConnectTimeoutException: Connect to sonatype-download.global.ssl.fastly.net:443

解决：登录 → System → Capabilities → 禁用 Outreach:Management

三、仓库类型与创建

3.1 四种仓库类型

类型	作用	典型用例
proxy	代理远程公共仓库	maven-central（代理 Maven Central）
hosted	托管本地仓库	maven-releases（内部发布版）、maven-snapshots（快照版）
group	把多个仓库组合	maven-public（把 maven-central / releases / snapshots 合并）
docker (proxy/hosted/group)	Docker 镜像仓库	docker-hosted

3.2 默认仓库

名称	类型	格式	备注
`maven-central`	proxy	maven2	Maven Central（`https://repo1.maven.org/maven2/`）
`maven-releases`	hosted	maven2	发行版
`maven-snapshots`	hosted	maven2	快照版
`maven-public`	group	maven2	把上面三个合并，客户端配这个
`nuget-*`	various	nuget	.NET 用，不关心

3.3 创建阿里云 Maven 镜像

场景：Maven Central 在国内太慢，加阿里云代理并放在 group 第一位。

Create repository → maven2 (proxy)
配置：
- Name: aliyun-maven-central
- URL: https://maven.aliyun.com/repository/public
在 maven-public group 里把 aliyun-maven-central 加进去，顺序调到最上面

四、Maven 客户端配置

4.1 settings.xml 镜像

1
2
3
4
5
6
7
8
9


<settings>
 <mirrors>
 <mirror>
 <id>nexus</id>
 <mirrorOf>*</mirrorOf>
 <url>http://internal.example.com:8081/repository/maven-public/</url>
 </mirror>
 </mirrors>
</settings>

<mirrorOf>*</mirrorOf>：拦截所有 Maven 请求，全部走 Nexus。生产环境推荐。

4.2 部署认证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<settings>
 <servers>
 <server>
 <id>nexus</id>
 <username>admin</username>
 <password>{{REDACTED}}</password>
 </server>
 <server>
 <id>releases</id>
 <username>admin</username>
 <password>{{REDACTED}}</password>
 </server>
 <server>
 <id>snapshots</id>
 <username>admin</username>
 <password>{{REDACTED}}</password>
 </server>
 </servers>
</settings>

服务器 ID 要和 pom.xml 的 <distributionManagement> 一致（如 releases、snapshots）。

五、Docker 私有仓库

5.1 创建 docker-hosted 仓库

Create repository → docker (hosted)
配置：
- Name: docker-hosted（自定义）
- HTTP 端口：8082（必须勾选"启用 HTTP"）
- 启用 Allow anonymous docker pull（按需）
- Blob store: 新建 docker

5.2 启用 Docker Bearer Token

Security → Realms
把 Docker Bearer Token 移到 Active 列表

5.3 防火墙 + 端口映射

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 内网 Docker 主机：8081（管理 UI）+ 8082（docker API）
# 公网：用 nginx 反代 8082 → 13004

# /etc/nginx/conf.d/nexus-docker.conf
server {
 listen 13004;
 server_name docker.internal.example.com;
 client_max_body_size 0;
 location / {
 proxy_pass http://<nexus_ip>:8082;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 }
}

5.4 客户端使用

不安全模式（HTTP）：

1
2
3
4
5
6
7
8
9


# /etc/docker/daemon.json
{
 "insecure-registries": [
 "internal.example.com:13001",
 "internal.example.com:13004"
 ]
}

systemctl restart docker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 登录
docker login http://internal.example.com:13004 -u admin -p {{REDACTED}}

# 打 tag + 推送
docker tag lwd/jdk:8u381-3 \
 internal.example.com:13004/docker-<your-org>/base/lwd/jdk:8u381-3
docker push internal.example.com:13004/docker-<your-org>/base/lwd/jdk:8u381-3

# 拉取
docker pull internal.example.com:13004/docker-<your-org>/base/lwd/jdk:8u381-3

安全模式（HTTPS）：配域名 + 证书，daemon.json 不需要 insecure-registries。

六、上传第三方 jar 包

6.1 创建 `3rdParty` 仓库

Create repository → maven2 (hosted)
Name: 3rdParty
Deployment policy: Allow redeploy（允许重复部署）

6.2 加入 `maven-public` group

把 3rdParty 加进 maven-public，方便客户端引用。

6.3 mvn settings.xml 加 server

1
2
3
4
5


<server>
 <id>3rdParty</id>
 <username>admin</username>
 <password>{{REDACTED}}</password>
</server>

6.4 上传 jar

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 1. 本地安装（可选，本地仓库也保留一份）
mvn install:install-file \
 -Dfile='C:\Users\user\Downloads\monitorservice.jar' \
 -DgroupId='com.example' \
 -DartifactId='monitorservice' \
 -Dversion='1.0.0' \
 -Dpackaging=jar

# 2. 上传到 Nexus
mvn deploy:deploy-file \
 -Dfile='C:\Users\user\Downloads\monitorservice.jar' \
 -DgroupId='com.example' \
 -DartifactId='monitorservice' \
 -Dversion='1.0.0' \
 -Dpackaging=jar \
 -Durl=http://internal.example.com:8081/repository/3rdParty/ \
 -DrepositoryId=3rdParty

6.5 引用上传的 jar

1
2
3
4
5
6


<!-- pom.xml -->
<dependency>
 <groupId>com.example</groupId>
 <artifactId>monitorservice</artifactId>
 <version>1.0.0</version>
</dependency>

七、清理 Blob 节省空间

Docker 镜像 push/pull 多了，Blob store 会越来越大。Nexus 提供了"Compact blob store"任务清理。

登录 Nexus → Administration → System → Tasks
Create task → Admin - Compact blob store
选 blob store（如 docker）
设置定时（如每周日凌晨）
触发后立即会清理"软删除"的数据（只保留一个 tag 引用的 blob，删除未引用的）

八、Nexus 3 vs Harbor vs Artifactory

维度	Nexus 3	Harbor	Artifactory
类型	通用制品库	镜像仓库为主	通用制品库
镜像支持	一般（V2 API）	最强（专门为镜像设计）	强
Maven 支持	最强	无	强
npm / pypi 支持	强	无	强
免费版功能	完整	完整	社区版受限
企业级	OSS / PRO	OSS	OSS / PRO
适合	Java 团队	Docker 镜像为主	大企业、混合制品

经验法则：

Java 团队为主 → Nexus 3（最稳）

纯 Docker 镜像管理 → Harbor（更专业）

多语言、多制品类型（npm / pypi / docker / maven / go）→ Artifactory（最全）

九、2024+ 视角补充

本文写于 2024-12，2025-2026 期间 Nexus 关键演进：

Sonatype Nexus Repository 3.78+ LTS（2025 起）：JDK 17 / 21 强制要求，3.70 之前版本 EOL——升级必做
Nexus Repository Pro 商业化加强：聚焦 C++ / .NET / AI 模型 制品管理（Blob 存储 + 元数据 + 审计）
Container Registry 体验升级：3.75+ Docker Bearer Token 性能优化，K8s 频繁拉镜像场景比之前快 30%
AI 模型仓库（2025-Q3 引入）：原生支持 HuggingFace / Ollama 格式模型制品——LLM 团队的私有模型管理
SBOM + 漏洞扫描（Pro）：CycloneDX 1.5+ / SPDX 2.3 报告自动生成
REST API 2.x 稳定：老的 service/rest/v1 进入维护，新接口 service/rest/v2 推荐
Terraform Provider 全面支持：IaC 方式管理 Repository——企业合规场景刚需

实战建议（2025-2026 视角）：Java 团队 Nexus 仍是首选；多语言 / AI 模型场景考虑迁移到 JFrog Artifactory 或 Harbor + 自建 AI 模型仓库组合；纯 Docker 镜像管理 Harbor 2.13+ 更专业。

十、扩展阅读

Nexus 官方仓库：github.com/sonatype/nexus-public
Nexus 官方文档：help.sonatype.com
阿里云 Maven 镜像：maven.aliyun.com
Maven 镜像配置指南：maven.apache.org/guides

Linux 开发环境搭建：JDK 8 / Maven 3.9 / NVM 与 Node 多版本管理

Fri, 30 Dec 2022 00:00:00 +0800

一、为什么是 2022 年这一份

2022 年这个时间点，Linux 后端/前端开发环境进入"标准化"阶段：

JDK 8 仍是企业主流（Spring Boot 2.x、Solr、大数据生态全靠它）
JDK 17 在 2021-09 发布后逐步成新项目首选
Maven 3.9（2023-01 发布）已经稳定，3.8 系列成为过去
NVM 0.39.x（2021-2022 系列）稳定，Node 14/16/18 三版本并行
npm 镜像 经历 npm.taobao.org → npmmirror.com 的迁移（2022-05）
systemd 全面接管 Java 服务启动

这一篇覆盖 JDK 8 / Maven / NVM 三大主力工具的安装、镜像、版本管理、与 systemd 集成——后端/前端开发者的"装机手册"。

阅读建议：本文是"工具栈"性质——按"装什么 → 配什么 → 用什么"组织。

二、JDK 8 安装（2022 仍主流）

2.1 下载与解压

1
2
3
4
5
6
7


# 下载 jdk-8u371-linux-x64.tar.gz
cd /usr/local
mkdir jdk
cd jdk
tar -xf jdk-8u371-linux-x64.tar.gz

# 解压到 /usr/local/jdk/jdk1.8.0_371

关于 8u371：Oracle JDK 8u371 是 2023-04 发布的。如果坚持 2022 时间线，可以选 8u341（2022-04）或 8u351（2022-10）。

2.2 环境变量

1

vim /etc/profile

1
2
3


export JAVA_HOME=/usr/local/jdk/jdk1.8.0_371
export CLASSPATH=$JAVA_HOME/bin:$JAVA_HOME/lib:$JAVA_HOME/jre/lib
export PATH=.:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH

1

source /etc/profile

2.3 验证

1
2
3
4


java -version
# java version "1.8.0_371"
# Java(TM) SE Runtime Environment (build 1.8.0_371-b11)
# Java HotSpot(TM) 64-Bit Server VM (build 25.371-b11, mixed mode)

三、Maven 3.9 安装

3.1 下载与解压

1
2
3
4
5
6
7
8


cd /usr/local/maven

# 3.9.2（2023-01 发布的 3.9.2 仍是很多 CI 的稳定选择）
wget https://archive.apache.org/dist/maven/maven-3/3.9.2/binaries/apache-maven-3.9.2-bin.tar.gz
tar -xf apache-maven-3.9.2-bin.tar.gz

# 改名
mv apache-maven-3.9.2 apache-maven-3.9.2

3.2 更换 settings.xml

把默认的 conf/settings.xml 替换成公司/个人定制的（国内镜像、代理、私服等）。

1
2
3
4
5
6


# 备份
cp /usr/local/maven/apache-maven-3.9.2/conf/settings.xml \
 /usr/local/maven/apache-maven-3.9.2/conf/settings.xml.bak

# 替换
vim /usr/local/maven/apache-maven-3.9.2/conf/settings.xml

3.3 环境变量

1

vim /etc/profile

1
2


export MAVEN_HOME=/usr/local/maven/apache-maven-3.9.2
export PATH=$MAVEN_HOME/bin:$PATH

1

source /etc/profile

3.4 验证

1
2
3
4
5
6


mvn -v
# Apache Maven 3.9.2 (21122926829f1ead511c958d89bd2f672198ae9f)
# Maven home: /usr/local/maven/apache-maven-3.9.2
# Java version: 1.8.0_371, vendor: Oracle Corporation, runtime: /usr/local/jdk/jdk1.8.0_371/jre
# Default locale: en_US, platform encoding: UTF-8
# OS name: "linux", version: "5.19.0-46-generic", arch: "amd64", family: "linux"

四、NVM 装 Node 多版本

4.1 下载 NVM 0.39.3

1

wget https://github.com/nvm-sh/nvm/archive/refs/tags/v0.39.3.tar.gz

4.2 安装

1
2
3
4


cd ~
mkdir .nvm
tar -zxvf v0.39.3.tar.gz --strip-components 1 -C /root/.nvm
rm -rf v0.39.3.tar.gz

4.3 环境变量

1

vim /etc/profile

1
2
3
4


export NVM_BIN="/root/.nvm/versions/node"
export NVM_DIR="/root/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

1
2
3
4


source /etc/profile
source ~/.zshrc

nvm --version

4.4 设置镜像

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Windows
nvm node_mirror https://npm.taobao.org/mirrors/node/
nvm npm_mirror https://npm.taobao.org/mirrors/npm/

# 2023-07-19 之后：原 taobao.org 改为 npmmirror.com
nvm node_mirror https://npmmirror.com/mirrors/node/
nvm npm_mirror https://npmmirror.com/mirrors/npm/

# Linux 改环境变量
vim /etc/profile
export NVM_NODEJS_ORG_MIRROR=https://npm.taobao.org/mirrors/node/

# 测试
curl $NVM_NODEJS_ORG_MIRROR

关于 npm 镜像迁移：2022-05-31 之后 npm.taobao.org 域名失效，全部迁移到 npmmirror.com。新项目必须用新域名。

4.5 装 Node 14

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 查可用版本
nvm ls-remote

# 装 Node 14.21.3
nvm install v14.21.3

# 验证
whereis node
# node: /root/.nvm/versions/node/v14.21.3/bin/node

node -v
# v14.21.3

npm -v
# 6.14.18

4.6 多版本共存

1
2
3
4
5
6
7
8
9


# 装第二个版本
nvm install v14.17.3

# 切换
nvm use v14.21.3

# 把 nvm 整体迁移到数据盘
mv /root/.nvm /data/jenkins/
# 改 NVM_DIR 路径

4.7 npm 镜像与 yarn

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 设 sass 镜像
npm config set sass_binary_site=https://npm.taobao.org/mirrors/node-sass

# 设 registry 镜像
npm config set registry https://registry.npmmirror.com

# 装 nrm（registry 切换器）
npm install -g nrm
nrm ls
nrm use taobao

# 装 yarn
npm i -g yarn
yarn -v
# 1.22.19

# 临时使用镜像
SASS_BINARY_SITE=https://npm.taobao.org/mirrors/node-sass npm install node-sass

五、zsh 下 Node 多版本切换

1
2
3
4


vim ~/.zshrc

export NODE_HOME=/data/jenkins/.nvm/versions/node/v14.17.3
export PATH=$NODE_HOME/bin:$PATH

六、Jenkins 跑前端项目

1
2
3
4
5
6
7
8
9


killall -9 node_modules || true
source /etc/profile
cd /home/docker/jenkins/workspace/safe-frontend-dev
rm -rf node_modules
npm config set sass_binary_site=https://npm.taobao.org/mirrors/node-sass
npm config set registry https://registry.npm.taobao.org/
npm -g i yarn
yarn
nohup yarn run serve > /dev/null 2>&1 &

七、用 systemd 启动 Java 微服务

7.1 准备启动脚本

1
2


# 写微服务启动脚本
vim /home/project/safety/sh/gateway.sh

1
2
3
4
5
6
7


#!/bin/bash
# gateway.sh 示例
export JAVA_HOME=/usr/local/jdk/jdk1.8.0_371
export PATH=$JAVA_HOME/bin:$PATH

cd /home/project/safety
java -jar gateway.jar --spring.profiles.active=prod

1

chmod +x /home/project/safety/sh/gateway.sh

7.2 写 service 文件

1

vim /etc/systemd/system/gateway.service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


[Unit]
Description=Gateway Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/home/project/safety/sh/gateway.sh
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

7.3 启动与管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


systemctl daemon-reload

# 启动
systemctl start gateway

# 开机启动
systemctl enable gateway

# 状态
systemctl status gateway

# 停止
systemctl stop gateway

# 失败重置
systemctl reset-failed gateway

# 卸载
rm -rf /etc/systemd/system/gateway.service

八、Java 反代启动命令

1
2
3
4
5


# 远程调试
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5003 \
 -Xverify:none \
 -cp /jar/xjrsoft-base/lib/*:/jar/xjrsoft-base/config \
 com.xjrsoft.BaseApplication

关于 jdwp 端口：调试端口要开放给开发机，不能开放在公网。生产环境记得移除 jdwp 参数。

九、envsubst 模板化配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# 模板 t.yaml
cat << "EOF" > t.yaml
systeminfo:
 OS: $OS
 user: $USER
 home: $HOME
 args:
 [
 "$args"
 ]
EOF

# 脚本 t.sh
cat << "EOF" > t.sh
#!/usr/bin/env bash
export OS=$(uname -s)
export args="/wait.sh 10.8.33.127:8848 -t 0"
ports=(100 200 300)
nodePort=30000
for p in ${ports[*]}; do
 nodePort=$[$nodePort+1]
 sed -i "8a \ - name: port$p\n port: $p\n targetPort: $p\n nodePort: $nodePort" t.yaml
done
envsubst < t.yaml > t1.yaml
EOF

bash t.sh

场景：用一份模板 + 环境变量生成 K8s manifest / docker-compose / nginx 配置。

十、前置知识 / 下一步

想看 JDK 17/21 新特性 → 翻本系列《JDK 升级与新特性》
想看 Maven 私服（Nexus / Artifactory）→ 翻本系列《Maven 私服搭建》
想看 Node 微前端构建优化 → 翻独立文章
想看 systemd 高级用法（target、socket 激活）→ 翻本系列《Linux 监控与系统性能工具》

十一、参考资源

Oracle JDK 8u 文档：https://docs.oracle.com/javase/8/docs/
Apache Maven 文档：https://maven.apache.org/
NVM GitHub：https://github.com/nvm-sh/nvm
Node.js 发布历史：https://nodejs.org/en/about/previous-releases
npmmirror：https://npmmirror.com/
systemd.service 文档：https://www.freedesktop.org/software/systemd/man/systemd.service.html

2024 视角：JDK 21 LTS 已经发布，Node 20/22 时代来了

2022 年写的那套"JDK 8 + Maven 3.9 + NVM + Node 14"在 2024 仍然可用，但新项目已经普遍升级。

一、JDK：JDK 17 已是新项目主流，JDK 21 LTS 已发布

JDK 21 LTS（2023-09 发布）是 2024 新项目首选——虚拟线程（Virtual Threads）正式 GA：

1
2
3
4
5
6
7
8
9


// 虚拟线程写法（替代传统 Thread / ExecutorService）
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
 IntStream.range(0, 10_000).forEach(i -> {
 executor.submit(() -> {
 Thread.sleep(Duration.ofSeconds(1));
 return i;
 });
 });
}

JDK 17 LTS（2021-09 发布）仍是 2024 大量"半新"项目的目标版本。
JDK 8（2014）已 2022-03 进入"个人免费但商业收费"模式（Oracle），2024 新项目不应该用 Oracle JDK 8——改用：
- Adoptium Eclipse Temurin 8（免费、长期维护）
- Amazon Corretto 8（AWS 维护）
- Alibaba Dragonwell 8（国内阿里维护，对 JVM 调优有特化）

装新版：

1
2
3
4
5


# Adoptium Temurin 21 (推荐)
apt install -y wget gnupg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -sc) main" > /etc/apt/sources.list.d/adoptium.list
apt update && apt install -y temurin-21-jdk

二、Maven 3.9 仍主流，但 Gradle 在 K8s / 云原生时代更受宠

Maven 3.9.6（2024-02 发布）是 2024 的稳定版，mvn -v 默认输出包含 Java version: 21.x。
Gradle 8.x（2023-10 起）支持 Java 21 + Kotlin 2.0，新项目可以选 Gradle。
Bazel（Google）和 Pants（Twitter）是更大规模 monorepo 项目的选择，但 2024 仍小众。

三、Node 20 LTS / 22 LTS 时代

Node 18（2022 LTS）2025-04 EOL，Node 20 LTS（2023-04）是 2024 主流，Node 22 LTS（2024-10 发布）开始被新项目采用。
NVM 0.39.7+ 仍是主流（但 2024 出现了 fnm 替代品，用 Rust 写、速度快 10 倍）。
Node 22 内置 --experimental-strip-types（原生运行 TypeScript，无需 ts-node 编译）。

1
2
3
4
5


# 2024 推荐：用 fnm 替代 nvm
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22
node -v # v22.x.x

四、cn 镜像的变化

registry.npmmirror.com 仍是 2024 首选 npm 镜像。
新增 https://registry.npmmirror.com/-/binary/ 提供 Node 二进制镜像（替代 taobao 老的 npm.taobao.org/dist/）。

corepack（Node 16+ 内置）一站式管理 yarn / pnpm：

1
2


corepack enable
corepack prepare yarn@stable --activate

五、systemd 启动 Java 服务的"v2 写法"

2024 推荐加 cgroup v2 资源限制 + 安全沙箱：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[Service]
Type=simple
User=appuser
ExecStart=/usr/local/jdk/bin/java -jar /opt/app.jar
Restart=always
RestartSec=10
# 资源限制
CPUQuota=200%
MemoryMax=2G
MemoryHigh=1G
# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
# 现代化：动态用户
DynamicUser=yes
# 日志
StandardOutput=journal
StandardError=journal

六、容器化时代的开发环境

2024 大量新项目**不再用"装在系统里的 JDK"**这套——直接走容器：

1
2
3
4
5


# 用容器跑 Maven 构建（避免污染系统）
docker run -it --rm \
 -v $PWD:/app -w /app \
 maven:3.9-eclipse-temurin-21 \
 mvn clean package

容器化开发环境的优势：

JDK 版本随项目走（不用每台机器装多个版本）
团队所有人 build 出来的产物一致
CI/CD 用同一镜像

Dev Container（VS Code Remote Containers）+ GitHub Codespaces 是 2024 的"标准动作"——开发机里根本不装 JDK，全在容器里。

WSL 远程开发环境搭建：从 Maven 到 IDE 集成

Sun, 15 Apr 2018 00:00:00 +0800

WSL 远程开发的核心理念

WSL 远程开发 = Linux 后端 + Windows 前端 IDE：

后端编译 / 构建 / 测试在 WSL（Linux 工具链）
前端编辑 / 调试 / Git 在 Windows（熟悉工具）
文件系统：项目放在 WSL，IDE 远程打开

好处：

Linux 工具链（apt、bash、coreutils）
Windows IDE（IntelliJ IDEA / VSCode / Cursor）
不需要 Dual Boot / VirtualBox
文件 IO 通过 9P 协议

WSL2 时代

2019 年 WSL2 GA 后，WSL 2 相比 WSL 1：

完整 Linux 内核
文件 IO 5~20 倍快
完整 syscall（Docker / ptrace / cgroups）

在 WSL 中安装 Maven

1. 准备

1
2
3
4
5
6
7
8


# 检查 WSL 版本
wsl -l -v
# NAME STATE VERSION
# Ubuntu-22.04 Running 2

# 切换默认用户为 root（可选）
# PowerShell 中：
wsl -u root -d Ubuntu-22.04

2. 下载 Maven

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 进入 WSL
wsl

# 切到 root（如有需要）
sudo su -

# 下载并解压到 /opt
cd /usr/local
sudo wget https://archive.apache.org/dist/maven/maven-3/3.9.14/binaries/apache-maven-3.9.14-bin.tar.gz

# 解压
sudo tar -zxvf apache-maven-3.9.14-bin.tar.gz -C /opt/

# 创建符号链接
sudo ln -s /opt/apache-maven-3.9.14 /opt/maven

3. 配置环境变量

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 写入 ~/.zshrc
sed -i '$a \
export M2_HOME=/opt/maven \
export PATH=$M2_HOME/bin:$PATH' ~/.zshrc

# 验证
cat ~/.zshrc | tail -5

# 重新加载
source ~/.zshrc

# 验证 Maven
mvn -v

输出：

1
2
3
4
5


Apache Maven 3.9.14 (9b613dcf7b...)
Maven home: /opt/maven
Java version: 21.0.10, vendor: Liberica, runtime: ...
Default locale: en, platform encoding: UTF-8
OS name: "linux", version: "...", arch: "amd64", family: "unix"

4. 配置 Maven 镜像

1
2


# 修改 settings.xml
nvim /opt/maven/conf/settings.xml

1
2
3
4
5
6


<mirror>
 <id>aliyun-public</id>
 <name>阿里云公共仓库</name>
 <url>https://maven.aliyun.com/repository/public</url>
 <mirrorOf>central</mirrorOf>
</mirror>

5. 用 sdkman 管理多版本（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 安装 sdkman
curl -s "https://get.sdkman.io" | bash
source ~/.sdkman/bin/sdkman-init.sh

# 装多个 Maven
sdk install maven 3.9.14
sdk install maven 3.8.9

# 切换
sdk use maven 3.9.14

IDE 集成 WSL

IntelliJ IDEA

打开 WSL 项目

File → New → Project from Existing Sources
浏览路径，输入 \\wsl$\Ubuntu-22.04\path\to\project
或：File → Open → Recent → WSL

配置 Maven 路径

Settings → Build, Execution, Deployment → Build Tools → Maven

Maven home directory: \\wsl$\Ubuntu-22.04\opt\maven
或：/opt/maven（用 WSL 内部路径）
User settings file: \\wsl$\Ubuntu-22.04\home\<user>\.m2\settings.xml
Local repository: \\wsl$\Ubuntu-22.04\home\<user>\.m2\repository

2024+ 的 IDEA Ultimate 支持 WSL 集成，直接识别 WSL 发行版，无需 \\wsl$ 前缀。

远程 SDK

Project Structure → Platform Settings → SDKs → + → WSL

选择 WSL 发行版（Ubuntu-22.04）
选择 Java 路径（如 /opt/jdk21）
OK

运行 / 调试

IDEA 直接在 WSL 中执行 mvn 命令。Console 输出在 WSL 终端（可在 IDEA 内部显示）。

VSCode / Cursor

安装 WSL 扩展

WSL（Microsoft 官方）

在 WSL 中打开

1
2
3
4
5


# PowerShell 中
wsl -d Ubuntu-22.04
code .
# 或
cursor .

配置

.vscode/settings.json：

1
2
3
4


{
 "remote.WSL.fileSystem.polling": true,
 "terminal.integrated.defaultProfile.linux": "zsh"
}

文件系统性能

WSL 1 vs WSL 2

场景	WSL 1	WSL 2
启动速度	快	中
文件 IO	慢（9P 桥接）	快（虚拟磁盘）
系统调用兼容	部分	完整
内存管理	共享	独立 VM

项目放哪？

位置	推荐	原因
WSL 内部（如 `~/projects/`）	✅	文件 IO 快
Windows（如 `C:\projects\`）	❌	跨 OS 文件 IO 慢

经验法则：把项目放在 WSL 文件系统（如 ~/projects/），IDE 通过 \\wsl$\... 访问。

WSL 配置

.wslconfig（Windows 用户目录）

1
2
3
4
5
6
7


[wsl2]
memory=4GB # 限制 WSL 内存
processors=4 # 限制 CPU 核数
swap=8GB # Swap 大小
swapFile=D:\wsl-swap.vhdx
localhostForwarding=true
sparseVhd=true # 自动压缩 vhdx

wsl.conf（WSL 内部）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# /etc/wsl.conf
[automount]
enabled=true
options=metadata,umask=022
mountFsTab=true

[network]
generateHosts=true
generateResolvConf=true

[interop]
enabled=true
appendWindowsPath=true

常见工作流

工作流 1：纯 Linux 开发

1
2
3
4
5


wsl
cd ~/projects/my-app
# 用 vim / nano / emacs 编辑
mvn clean package
java -jar target/my-app.jar

工作流 2：混合开发（推荐）

Windows 端：IDEA / VSCode / Cursor 打开项目
后端编译运行在 WSL
数据库 / Redis / Nginx 用 docker compose（WSL 内）
浏览器 / Postman / 数据库客户端在 Windows

工作流 3：远程 SSH 风格

1
2
3
4
5


# 用 Windows Terminal + SSH 客户端
ssh user@your-wsl-host

# 或直接 PowerShell 进入
wsl ~ -d Ubuntu-22.04

Docker in WSL

WSL2 内 Docker 部署有 3 种方案：

方案 1：Docker Desktop for Windows（推荐）

自动用 WSL2 后端
Docker CLI 也在 WSL 中可用
适合一般场景

方案 2：WSL 独立 Docker daemon

1
2
3
4


# 在 WSL 内安装 docker.io
sudo apt install -y docker.io
sudo systemctl start docker
sudo usermod -aG docker $USER

方案 3：Rancher Desktop / Podman

轻量替代 Docker Desktop
完全开源

网络访问

WSL2 通过 localhost 与 Windows 互访：

WSL 访问 Windows：http://host.docker.internal 或 \\wsl$\
Windows 访问 WSL：http://localhost:<port>（WSL 转发到 Windows localhost）

1
2


# .wslconfig
localhostForwarding=true

调试案例

问题 1：Maven 找不到 JAVA_HOME

1
2
3
4
5
6
7


# 检查
echo $JAVA_HOME
which java
java -version

# 设置
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

问题 2：IDEA 找不到 WSL 路径

Settings → Appearance & Behavior → System Settings → WSL：

启用 WSL 集成
选择发行版

问题 3：文件修改无响应

IDEA 默认每 3 秒刷新文件。WSL 文件变更需要更频繁：

1
2
3
4
5
6
7


// .vscode/settings.json
{
 "files.watcherExclude": {
 "**/target/**": true,
 "**/node_modules/**": true
 }
}

项目级 init 脚本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


#!/bin/bash
# ~/bin/dev-env.sh

# 安装基础工具链
sudo apt update
sudo apt install -y openjdk-21-jdk maven nodejs npm zsh git curl

# 安装 oh-my-zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
chsh -s $(which zsh)

# 安装 sdkman
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 安装 Maven
sdk install maven 3.9.14

# 装 IDEA 替代品（可选）
# ...

完整开发体验检查清单

WSL2 已启用
zsh + oh-my-zsh + Powerlevel10k
fcitx5 五笔
sdkman 管理 JDK / Maven
Docker Desktop 或 WSL Docker
Git 配置（user.name / user.email）
SSH key 已加到 GitHub
项目在 ~/projects/（WSL 文件系统）
IDE 通过 \\wsl$\... 打开
中文字体（Cantarell / Fira Code / Meslo）

下一步

WSL 完整使用手册，看 2017-01-15《WSL2 完整使用手册》
Linux 工作站基础配置，看 2014-01-15《Linux 工作站基础配置》
远程开发常见问题排查，看 2018-04-15 后 WSL2 高级用法

参考资料

WSL 官方文档：https://learn.microsoft.com/en-us/windows/wsl/
Maven 官方：https://maven.apache.org/
sdkman：https://sdkman.io/
IntelliJ IDEA WSL 集成：https://www.jetbrains.com/help/idea/how-to-use-wsl-development-environment.html

Windows 绿色版开发工具链：CMake、MinGW、Maven、Gradle、nvm、ffmpeg、sqlite3 与 protoc 全配置

Sun, 15 Mar 2015 00:00:00 +0800

一、为什么要在 Windows 上做"绿色版"开发工具链

每台新机器、每个新客户现场、每个虚拟机都要重新装一遍开发环境，是 Windows 程序员最痛苦的事之一。理想状态是：一个 D:\portable\ 目录，拷过去就能干活。

本文把开发时最常用的小工具（不包含 IDE 与 Docker）整理成一份"解压即用"配置手册：

C/C++ 编译：CMake + MinGW
JVM 构建：Maven + Gradle
Node 多版本：nvm-windows
多媒体处理：ffmpeg
嵌入式数据库：sqlite3
IDL 编译：protoc
搜索引擎：Elasticsearch（本地开发用）

二、C/C++ 工具链：CMake + MinGW

2.1 MinGW-w64 下载与配置

推荐 niXman/mingw-builds-binaries，选 x86_64-13.x.x-release-posix-seh-ucrt-rt_v11-rev0.7z（ucrt 是 Win10/11 推荐运行时）。

或者从 winlibs.com 下整合好的 zip。

解压到 D:\portable\dev\mingw64，加到 PATH：

1

PATH=D:\portable\dev\mingw64\bin

验证：

1
2
3
4
5
6


gcc --version
# gcc.exe (MinGW-W64) 13.2.0

# 把 mingw32-make.exe 复制一份改名 make
cp D:\portable\dev\mingw64\bin\mingw32-make.exe D:\portable\dev\mingw64\bin\make.exe
make --version

2.2 CMake 下载与配置

cmake.org/download 下载 cmake-3.x.x-windows-x86_64.zip，解压到 D:\portable\dev\cmake-3.28.3-windows-x86_64\bin 加 PATH。

1
2


cmake --version
# cmake version 3.28.3

避坑：下载页有两个版本 *-windows-x86_64.msi（安装器）和 *-windows-x86_64.zip（绿色版），选 zip 才能 portable。

2.3 完整编译一个 hello.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


cmd /c cd. > hello.cpp

# 写代码（用 vim 或记事本）
cat > hello.cpp <<EOF
#include <iostream>
int main() {
 std::cout << "Hello, World!" << std::endl;
 return 0;
}
EOF

# 编译
g++ -c hello.cpp
g++ hello.o -o hello.exe
./hello.exe

2.4 用 CMake 跨平台构建

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


cmd /c cd. > CMakeLists.txt

cat > CMakeLists.txt <<EOF
cmake_minimum_required(VERSION 3.0)
project(hello)
add_executable(hello hello.cpp)
if(WIN32)
 set(CMAKE_CXX_FLAGS "-static-libgcc -static-libstdc++")
endif()
EOF

mkdir build && cd build
cmake -G "Unix Makefiles" ../
make
./hello.exe

-static-libgcc -static-libstdc++ 关键！不写这两个就依赖 libgcc_s_seh-1.dll 等动态库，绿色拷贝出去会缺 DLL。

2.5 32 位与 64 位交叉编译

1
2


g++ -m32 hello.cpp -o hello32.exe
g++ -m64 hello.cpp -o hello64.exe

三、JVM 构建：Maven 与 Gradle

3.1 Maven 3.9

maven.apache.org 下载 apache-maven-3.9.4-bin.zip，解压到 D:\portable\dev\apache-maven-3.9.4。

环境变量：

1
2


MAVEN_HOME=D:\portable\dev\apache-maven-3.9.4
PATH=%PATH%;%MAVEN_HOME%\bin

注：%MAVEN_HOME% 这种写法在 PowerShell 里要用 $env:MAVEN_HOME，cmd 才是 %...%。

%MAVEN_HOME%\conf\settings.xml 必改项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 1. 镜像（公司 Nexus / 阿里云） -->
<mirrors>
 <mirror>
 <id>internal-nexus</id>
 <mirrorOf>central</mirrorOf>
 <url>http://internal.example.com:8081/repository/maven-public/</url>
 </mirror>
</mirrors>

<!-- 2. 本地仓库放 D 盘 -->
<localRepository>D:\portable\dev\.m2\repository</localRepository>

3.2 Maven 找不到插件 `spring-boot-maven-plugin` 的坑

pom.xml 里只声明 <plugin> 不带 <version>，会报：

1

[ERROR] Plugin 'org.springframework.boot:spring-boot-maven-plugin:' not found

原因：<pluginManagement> 里引用时未指定版本，或继承的 spring-boot-starter-parent 缺失。修法：

1
2
3
4
5
6
7
8
9


<build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <version>2.3.0.RELEASE</version> <!-- 显式版本 -->
 </plugin>
 </plugins>
</build>

3.3 Gradle 8.x

gradle.org/releases 下 gradle-8.5-bin.zip，解压到 D:\portable\dev\gradle-8.5。

1

PATH=D:\portable\dev\gradle-8.5\bin

3.4 引入本地第三方 jar（Maven 实战）

业务 jar 不在公共仓库时，不能用 mvn install，得在 common 模块的 pom.xml 里加 scope=system：

1
2
3
4
5
6
7


<dependency>
 <groupId>com.example</groupId>
 <artifactId>thirdparty-jar</artifactId>
 <version>1.0.0</version>
 <scope>system</scope>
 <systemPath>${project.basedir}/src/main/resources/lib/thirdparty.jar</systemPath>
</dependency>

文件布局：

1
2
3


common/
├── src/main/resources/lib/thirdparty.jar
├── pom.xml

这种方式是反模式（jar 进 git），Maven 官方不推荐；正路是搭 Nexus / 阿里云 Maven 仓库。实在没私有仓库时，临时用。

四、Node 多版本：nvm-windows

4.1 下载

coreybutler/nvm-windows/releases 下载 nvm-noinstall.zip，解压到 D:\portable\dev\nvm。

settings.txt 配置镜像（阿里云）：

1
2
3
4


root: D:\portable\dev\nvm
path: D:\portable\dev\nodejs
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

4.2 常用命令

1
2
3
4
5


nvm install 18.20.0 # 装 Node 18 LTS
nvm install 20.11.0 # 装 Node 20 LTS
nvm use 18.20.0 # 切换到 18
nvm list # 已装版本
nvm alias default 20.11.0

五、ffmpeg：音视频处理

5.1 下载

ffmpeg.org 找 gyan.dev 或 BtbN 提供的构建包，下载 ffmpeg-release-essentials.zip，解压到 D:\portable\dev\ffmpeg，把 bin 加 PATH：

1

ffmpeg -version

5.2 YouTube 1080p Adaptive 音视频合并

YouTube-DL 抓下来的 1080p 视频是音视频分离的（一个 .mp4、一个 .webm），合成：

1

ffmpeg -i input.mp4 -i input.webm -strict -2 -acodec copy -vcodec copy output.mp4

-strict -2：启用实验性 AAC 编码（合成 1080p 必须）；
-acodec copy / -vcodec copy：流复制，秒级完成。

5.3 截图、剪切、转码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 截取第 5 秒的帧
ffmpeg -i input.mp4 -ss 5 -vframes 1 cover.jpg

# 裁剪 1080p → 480p
ffmpeg -i input.mp4 -vf scale=854:480 output_480p.mp4

# 剪切 00:30 - 01:30
ffmpeg -i input.mp4 -ss 00:00:30 -to 00:01:30 -c copy clip.mp4

# 视频转 GIF
ffmpeg -i input.mp4 -vf "fps=15,scale=480:-1" out.gif

六、sqlite3：嵌入式数据库

6.1 下载

sqlite.org/download.html 拉两个 zip：

sqlite-dll-win64-x64-3410200.zip：sqlite3.dll
sqlite-tools-win32-x86-3410200.zip：命令行工具

解压到 D:\portable\dev\sqlite3，把 sqlite3.exe 加 PATH。

6.2 基础使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 打开/创建 db
sqlite> .open test.db

# 常用元命令
.databases # 列出所有 db
.tables # 列出所有表
.schema user # 查看 user 表 DDL
.headers on
.mode column

# 退出
.exit

6.3 用 Navicat / IDEA 连接

sqlite3 本身支持 TCP 监听，但用 Navicat / IDEA 直连 .db 文件更直接：

1
2
3
4
5
6


# Navicat
连接类型：SQLite
数据库文件：D:\path\to\test.db

# IDEA Database 工具
Data Sources → SQLite → 选择 .db 文件

实战经验：很多"配置文件中心"工具（如 H2、HSQLDB、Apache Geode）底层都支持 sqlite 协议；本地开发、单元测试时 sqlite 比 MySQL 快 10 倍。

七、protoc：protobuf 编译

7.1 下载

protocolbuffers/protobuf/releases 下载 protoc-21.3-win64.zip（21.x 是 proto3 稳定版），解压到 D:\portable\dev\protoc-21.3\bin，加 PATH。

7.2 编译 .proto

1
2
3


protoc --java_out=./src/main/java -I. user.proto
protoc --go_out=./pkg -I. user.proto
protoc --python_out=. -I. user.proto

-I（或 --proto_path）：proto 文件搜索目录
--xxx_out：目标语言输出目录

7.3 gRPC 代码生成

protoc 默认不生成 gRPC 服务端 / 客户端 stub，需要装 plugin：

1
2
3
4
5


# Java
protoc --java_out=. --grpc-java_out=. -I. user.proto

# Go
protoc --go_out=. --go-grpc_out=. -I. user.proto

详见 grpc/grpc-java / grpc/grpc-go 文档。

八、Elasticsearch：本地开发用

8.1 下载

elastic.co/downloads/past-releases 选 7.17.x 或 8.x 的 Windows zip（不推荐用 msi）。

1

D:\portable\dev\elasticsearch-8.11.0\bin\elasticsearch.bat

8.2 配置文件

config/elasticsearch.yml 关键项：

1
2
3
4
5
6


cluster.name: dev-cluster
node.name: dev-node-1
network.host: 127.0.0.1
http.port: 9200
discovery.type: single-node  # 单节点模式，省去选举
xpack.security.enabled: false # 本地开发关掉安全

8.3 启动

1
2
3
4
5


# 不能用 root（Windows 默认 Administrator 即可）
bin\elasticsearch.bat

# 验证
curl http://127.0.0.1:9200

8.4 Head 插件

elasticsearch-head 是个 Chrome 插件 + 老式 Node 项目，可视化查看 index：

1
2
3
4
5


git clone https://github.com/mobz/elasticsearch-head
cd elasticsearch-head
npm install
npm run start
# 浏览器打开 http://localhost:9100

8.x 之后 Kibana 自带 Dev Tools Console，更现代，建议用 Kibana。

九、必备小工具

工具	用途	绿色版路径
HeidiSQL	MySQL/MariaDB 客户端	`D:\portable\dev\heidisql`
RedisDesktopManager	Redis GUI	`D:\portable\dev\rdm`
Caddy	HTTP 服务器	`D:\portable\dev\caddy`
7-Zip	解压	系统自带 / scoop 装
ripgrep	文件搜索	`D:\portable\dev\rg\rg.exe`

十、便携版目录约定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


D:\portable\
├── dev\
│ ├── mingw64\
│ ├── cmake-3.28.3\
│ ├── apache-maven-3.9.4\
│ ├── gradle-8.5\
│ ├── nvm\
│ ├── nodejs\ # nvm 切版本时切换的软链目标
│ ├── ffmpeg\
│ ├── sqlite3\
│ ├── protoc-21.3\
│ ├── elasticsearch-8.11.0\
│ ├── caddy\
│ └── .m2\ # 本地 Maven 仓库
└── path\bin\ # 全部 exe 软链

十一、常见坑

现象	原因	对策
g++ 链接缺 dll	默认动态链接	加 `-static-libgcc -static-libstdc++`
Maven 下载 jar 卡死	仓库无代理	配 Nexus / 阿里云镜像
Gradle 启动报 JAVA_HOME 错	JDK 路径含空格	重装 JDK 到无空格目录如 `C:\java\jdk-17`
ffmpeg 合成提示 “Experimental”	AAC 编码	加 `-strict -2`
sqlite3 中文乱码	命令行编码	`chcp 65001` 切 UTF-8
protoc 找不到 .proto	`-I` 路径错	绝对路径或 cd 到 .proto 所在目录
Elasticsearch 启动 OOM	JVM 堆太小	`config/jvm.options` 加 `-Xms2g -Xmx2g`

十二、下一步

C/C++ 进阶：CMake + vcpkg / Conan 跨平台包管理
Maven 进阶：maven-shade-plugin 打 fat jar、maven-assembly-plugin 自定义打包
Node 进阶：pnpm / yarn / corepack 多包管理器
Elasticsearch 进阶：用 Docker 部署集群（参考 2019-06-20《Docker 进阶与运维》）

十三、参考资料

Maven 全套实战：从安装到多模块企业级构建

Thu, 20 Feb 2014 00:00:00 +0800

Maven 全套实战：从安装到多模块企业级构建

背景与价值

Maven 是 Java 生态事实标准构建工具（Ant 已老、Gradle 学习成本高）。核心价值：

依赖管理：自动下载 jar 及其传递依赖，避免版本冲突
标准化结构：src/main/java、src/test/java 等约定优于配置
多模块管理：父子 POM 继承 + dependencyManagement 统一版本
构建生命周期：compile / test / package / install / deploy 一键式

本文按"安装 → 核心配置 → 多模块 → 实战坑"完整路径展开，基于 Maven 3.9.x 实测。

安装与配置

1. 下载解压

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Linux
curl -O https://archive.apache.org/dist/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz
mkdir -p /opt/maven
tar -zxvf apache-maven-3.9.6-bin.tar.gz -C /opt/maven

# 配置环境变量
export JAVA_HOME=/opt/java/jdk1.8.0_381
export MAVEN_HOME=/opt/maven
export PATH=.:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$MAVEN_HOME/bin:$PATH

# 验证
mvn -version
# Apache Maven 3.9.6 (8c8575b0e1b8...)
# Java version: 1.8.0_381

2. 全局配置文件 `${maven_home}/conf/settings.xml`

settings.xml 集中管理仓库镜像、代理、profile、服务器认证等全局配置，避免每个项目单独配。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">

 <!-- 本地仓库路径（默认 ${user.home}/.m2/repository） -->
 <!--<localRepository>/path/to/local/repo</localRepository>-->

 <!-- 离线模式（无法联网时） -->
 <!--<offline>false</offline>-->

 <!-- 代理（公司内网访问外网 Maven 中央仓库时） -->
 <proxies>
 <proxy>
 <id>myproxy</id>
 <active>true</active>
 <protocol>http</protocol>
 <host>proxy.example.com</host>
 <port>8080</port>
 <username>proxyuser</username>
 <password>{{PROXY_PASSWORD}}</password>
 <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts>
 </proxy>
 </proxies>

 <!-- 服务器认证（部署到 Nexus / 私库时用） -->
 <servers>
 <server>
 <id>nexus-releases</id>
 <username>{{NEXUS_USER}}</username>
 <password>{{NEXUS_PASSWORD}}</password>
 </server>
 </servers>

 <!-- 镜像（关键：阿里云加速国内下载） -->
 <mirrors>
 <mirror>
 <id>aliyun-public</id>
 <name>阿里云 Maven 公共仓库</name>
 <url>https://maven.aliyun.com/repository/public</url>
 <mirrorOf>central</mirrorOf>
 </mirror>
 </mirrors>

 <!-- 多环境 Profile -->
 <profiles>
 <profile>
 <id>jdk-1.8</id>
 <activation>
 <activeByDefault>true</activeByDefault>
 </activation>
 <properties>
 <maven.compiler.source>1.8</maven.compiler.source>
 <maven.compiler.target>1.8</maven.compiler.target>
 </properties>
 </profile>
 </profiles>
</settings>

3. 阿里云镜像配置（关键）

国内访问 Maven 中央仓库（repo1.maven.org）经常超时，建议配置阿里云镜像：

仓库类型	阿里云地址
公共仓库	`https://maven.aliyun.com/repository/public`
Google	`https://maven.aliyun.com/repository/google`
Spring	`https://maven.aliyun.com/repository/spring`
Apache Snapshots	`https://maven.aliyun.com/repository/apache-snapshots`

配置示例（settings.xml 镜像）：

1
2
3
4
5
6


<mirror>
 <id>aliyun-spring</id>
 <name>阿里云 Spring 仓库</name>
 <url>https://maven.aliyun.com/repository/spring</url>
 <mirrorOf>spring-milestones,spring-snapshots</mirrorOf>
</mirror>

核心概念

1. 坐标（GAV）

每个 Maven 构件由三要素唯一定位：

1
2
3
4
5


<dependency>
 <groupId>org.springframework.boot</groupId> <!-- 组织 -->
 <artifactId>spring-boot-starter-web</artifactId> <!-- 项目 -->
 <version>3.2.0</version> <!-- 版本 -->
</dependency>

2. 仓库类型

类型	位置	用途
本地仓库	`~/.m2/repository/`	已下载的依赖
中央仓库	`repo1.maven.org`	Maven 官方仓库（默认）
私服	Nexus / Artifactory	公司内网，缓存 + 部署
镜像仓库	阿里云 / 华为云	中央仓库的国内镜像

3. 依赖范围（Scope）

Scope	编译	测试	运行时	例子
`compile`（默认）	✅	✅	✅	`spring-core`
`provided`	✅	✅	❌	`servlet-api`（容器提供）
`runtime`	❌	✅	✅	`JDBC 驱动`
`test`	❌	✅	❌	`JUnit`
`system`	✅	✅	❌	引用本地 jar（不推荐）

4. 生命周期阶段

1
2
3
4
5
6


mvn clean # 清理 target/
mvn compile # 编译 main
mvn test # 编译并运行测试
mvn package # 打包成 jar/war
mvn install # 安装到本地仓库（供其他模块引用）
mvn deploy # 部署到远程私服

多模块项目（企业级核心）

1. 父 POM 约定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


my-project/ # 父项目根目录
├── pom.xml # 父 POM（packaging=pom）
├── my-app/ # 主应用模块
│ ├── pom.xml
│ └── src/
├── my-common/ # 公共工具模块
│ ├── pom.xml
│ └── src/
└── my-api/ # API 定义模块
 ├── pom.xml
 └── src/

2. 父 POM 完整模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
 <modelVersion>4.0.0</modelVersion>

 <!-- 继承 Spring Boot Starter Parent（统一版本管理） -->
 <parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>2.6.14</version>
 <relativePath/>
 </parent>

 <groupId>com.example</groupId>
 <artifactId>my-project</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>pom</packaging>
 <name>my-project</name>

 <!-- 子模块清单 -->
 <modules>
 <module>my-common</module>
 <module>my-api</module>
 <module>my-app</module>
 </modules>

 <!-- 统一版本管理（子模块引用时不需要写版本号） -->
 <dependencyManagement>
 <dependencies>
 <!-- Spring Cloud -->
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-dependencies</artifactId>
 <version>${spring-cloud.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <!-- Spring Cloud Alibaba -->
 <dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-alibaba-dependencies</artifactId>
 <version>${spring-cloud-alibaba.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <!-- 项目内部模块 -->
 <dependency>
 <groupId>com.example</groupId>
 <artifactId>my-common</artifactId>
 <version>${project.version}</version>
 </dependency>
 </dependencies>
 </dependencyManagement>

 <!-- 公共依赖（所有子模块都会继承） -->
 <dependencies>
 <dependency>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <scope>provided</scope>
 </dependency>
 </dependencies>

 <!-- 统一属性 -->
 <properties>
 <java.version>1.8</java.version>
 <maven.compiler.source>${java.version}</maven.compiler.source>
 <maven.compiler.target>${java.version}</maven.compiler.target>
 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 <spring-cloud.version>2021.0.1</spring-cloud.version>
 <spring-cloud-alibaba.version>2021.0.1.0</spring-cloud-alibaba.version>
 </properties>

 <!-- 多环境 Profile -->
 <profiles>
 <profile>
 <id>dev</id>
 <activation>
 <activeByDefault>true</activeByDefault>
 </activation>
 <properties>
 <profile.name>dev</profile.name>
 </properties>
 </profile>
 <profile>
 <id>test</id>
 <properties>
 <profile.name>test</profile.name>
 </properties>
 </profile>
 <profile>
 <id>prod</id>
 <properties>
 <profile.name>prod</profile.name>
 </properties>
 </profile>
 </profiles>
</project>

3. 子模块 POM

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


<?xml version="1.0" encoding="UTF-8"?>
<project>
 <parent>
 <groupId>com.example</groupId>
 <artifactId>my-project</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 </parent>

 <artifactId>my-app</artifactId>
 <packaging>jar</packaging>

 <!-- 不需要写版本号（父 dependencyManagement 已管理） -->
 <dependencies>
 <dependency>
 <groupId>com.example</groupId>
 <artifactId>my-common</artifactId>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 </dependencies>
</project>

常用命令

命令	作用
`mvn clean`	清理 target 目录
`mvn compile`	编译主代码
`mvn test`	运行单元测试
`mvn package -DskipTests`	打包跳过测试
`mvn dependency:tree`	树形展示依赖
`mvn dependency:tree -Dincludes=commons-logging`	过滤特定依赖
`mvn help:effective-pom`	查看完整 POM（合并父子）
`mvn -Pprod clean package`	激活 prod profile 打包
`mvn -pl my-app -am package`	只构建 my-app 及其依赖模块

实战坑

1. 依赖冲突（`NoClassDefFoundError` / `NoSuchMethodError`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 查看依赖树
mvn dependency:tree -Dverbose

# 排除传递依赖
<dependency>
 <groupId>com.example</groupId>
 <artifactId>my-lib</artifactId>
 <exclusions>
 <exclusion>
 <groupId>commons-logging</groupId>
 <artifactId>commons-logging</artifactId>
 </exclusion>
 </exclusions>
</dependency>

2. JAR 包冲突定位

1
2
3
4
5
6


# 找哪个 jar 引入的
mvn dependency:tree -Dincludes=com.google.guava:guava

# 输出：
# [INFO] +- com.example:my-lib:jar:1.0:compile
# [INFO] | \- com.google.guava:guava:jar:30.0-jre:compile ← 这里

3. SNAPSHOT 版本不稳定

1.0.0-SNAPSHOT 表示"开发中快照"，Maven 默认每次构建都拉取最新。生产环境应锁定 release 版本。

4. `mvn package` 跳过测试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 方式 1：命令行参数
mvn package -DskipTests

# 方式 2：surefire 插件配置
<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-surefire-plugin</artifactId>
 <configuration>
 <skipTests>true</skipTests>
 </configuration>
</plugin>

5. 配置中心化 vs 分散

统一管理：父 POM dependencyManagement 集中版本
覆盖：子模块可显式覆盖（极少数情况）
避免：每个子模块独立写版本号（升级时全项目都要改）

Maven Wrapper（推荐）

mvnw 是项目自带的 Maven 包装脚本，避免开发者本地 Maven 版本不一致：

1
2
3
4
5
6
7
8
9


# 生成 wrapper（项目根目录执行一次）
mvn -N io.takari:maven:0.7.7:wrapper -Dmaven=3.9.6

# 提交到 Git
git add mvnw mvnw.cmd .mvn/
git commit -m "build: 添加 Maven Wrapper"

# 团队成员执行（无需安装 Maven）
./mvnw clean package

私服搭建（Nexus 3.x）

1
2
3
4
5
6


# Docker 一键启动
docker run -d \
 -p 8081:8081 \
 -v /data/nexus-data:/nexus-data \
 --name nexus \
 sonatype/nexus3:3.64.0

部署到 Nexus：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<!-- 项目 pom.xml -->
<distributionManagement>
 <repository>
 <id>nexus-releases</id> <!-- 对应 settings.xml server id -->
 <url>http://{{NEXUS_HOST}}:8081/repository/maven-releases/</url>
 </repository>
 <snapshotRepository>
 <id>nexus-snapshots</id>
 <url>http://{{NEXUS_HOST}}:8081/repository/maven-snapshots/</url>
 </snapshotRepository>
</distributionManagement>

<build>
 <plugins>
 <plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-deploy-plugin</artifactId>
 </plugin>
 </plugins>
</build>

1

mvn deploy # 部署到 Nexus

前置知识与下一步

前置：

Java 基础语法、IDE 使用
基本的命令行操作
了解 Spring Boot 项目结构

下一步：

复杂构建用 Maven Profile + Resource Filtering 实现多环境打包
配合 Dockerfile + CI/CD 一键出镜像
巨型项目切分用 Maven 多仓库 + 微服务，避免单仓库超大

小结

Maven 3.9 + 阿里云镜像 + 标准 settings.xml 是企业 Java 项目的"开箱即用"组合。多模块项目靠父 POM dependencyManagement 统一版本 + 子 POM 引用简化，是避免"依赖版本地狱"的关键。Maven Wrapper 解决了团队成员本地 Maven 版本不一致的痛点。Nexus 私服是企业内网依赖缓存 + 内部 jar 部署的标配。

2024+ 视角：Maven 4 预览 + Gradle 8 对比

Maven 4.0 关键变化（2024 仍在预发布）

POM 结构化：XML → 仍是 XML，但解析器重写（Lexical 三遍解析），速度 +30%
多语言项目支持：原 Maven 只管 Java，Maven 4 开始支持 JS / Python / Rust 子项目
dependencyManagement 路径表达式：支持 ${groupId:artifactId:type:version} 直接引用父项目
CI 集成深度增强：mvn verify 输出 SBOM（软件物料清单）——合规审计直接用
MVN Daemon（实验）：常驻进程 + 增量编译，类似 Gradle Daemon

Maven 4 升级路径

1
2
3
4
5
6
7
8


<!-- pom.xml 顶部 -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 ...
</project>

主要差异：

POM modelVersion 不变（仍是 4.0.0）
升级命令：mvn -P maven-4-upgrade verify（Maven 4 自带）
大部分插件需升级到 4.x 版本

Gradle 8.x 与 Maven 4 的 2024+ 对比

维度	Maven 4	Gradle 8.x
构建速度	较慢（提升 30%）	快 2-10 倍（增量 + 守护进程）
配置语言	XML	Kotlin DSL / Groovy
增量构建	需 mvn incremental	原生支持
多语言	实验	Kotlin Multiplatform / Android
生态稳定性	25 年沉淀，文档全	较新，插件质量参差
学习曲线	低（约定优于配置）	中（DSL 学习）
企业 Java 占比	70%+	15%

选型建议：

新项目（Kotlin / Android / 复杂构建）：Gradle 8.x
传统 Spring / 金融 / 政府：Maven 仍是首选——团队上手快、CI 配置简单
Kotlin Multiplatform / 跨平台：必须 Gradle

镜像配置的 2024+ 演进

阿里云 2023 年起对 Maven 中央仓库做了全量同步，但 2024 之后新增了：

华为云镜像：https://repo.huaweicloud.com/repository/maven/
腾讯云镜像：https://mirrors.cloud.tencent.com/nexus/repository/maven-public/
中国移动云镜像：https://mirrors.cmecloud.cn/repository/maven/

1
2
3
4
5
6
7


<mirrors>
 <mirror>
 <id>huawei-cloud</id>
 <url>https://repo.huaweicloud.com/repository/maven/</url>
 <mirrorOf>central</mirrorOf>
 </mirror>
</mirrors>

`dependencyManagement` 2024+ 进阶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<!-- BOM 引用（Bill of Materials）-->
<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-dependencies</artifactId>
 <version>3.4.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-alibaba-dependencies</artifactId>
 <version>2023.0.1.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

Maven Wrapper 的 2024+ 变化

1
2
3
4
5


# 旧版（Takari wrapper）
mvn -N io.takari:maven:0.7.7:wrapper -Dmaven=3.9.6

# 新版（Maven 官方 wrapper 3.2+）
mvn wrapper:wrapper -Dmaven=3.9.9

新版 wrapper 由 Maven 官方维护，不需要 Takari 仓库。

依赖冲突排查的 2024+ 新工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 1. mvn dependency:tree（老牌）
mvn dependency:tree -Dverbose -Dincludes=commons-logging:commons-logging

# 2. maven-dependency-plugin 3.6+：dependency:analyze
mvn dependency:analyze

# 3. Enforcer 插件：禁止某些依赖
<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-enforcer-plugin</artifactId>
 <version>3.4.1</version>
</plugin>

实战坑（2024+）

Spring Boot 3.x 必须 JDK 17+——Maven 3.8.x 之前的版本不支持 --add-opens，需用 3.9.x
Maven Central 在 2024-06 调整了 HTTPS 证书链——老 Maven 版本（< 3.6.3）需升级
Nexus 3.64+ 强制 HTTPS——HTTP 私服要升级或保留 HTTP 白名单
JCenter 2022 已停止服务——所有 jcenter() 引用要改 mavenCentral()

2024+ 推荐组合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


企业 Java 项目（Spring Boot 3.x）
├── Maven 3.9.x / Maven 4.0（2024+）
├── 阿里云镜像 + settings.xml
├── Maven Wrapper 3.2+
├── spring-boot-starter-parent 3.4.x
├── spring-cloud-dependencies 2024.0.x BOM
├── spring-cloud-alibaba-dependencies 2023.0.x BOM
├── 父 POM dependencyManagement 统一版本
├── 子 POM 引用无版本号
├── Nexus 3.64+ 私服（maven-releases + maven-snapshots）
└── mvn -Pprod clean package + Jib 打 Docker 镜像