Back to Details

ccmvn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maven Build with ccmvn

使用ccmvn进行Maven构建

The 
ccmvn
tool enables Maven to run in restricted sandbox environments where outbound HTTPS is blocked or DNS resolution is unavailable. It works by creating a local HTTP proxy that Maven uses to access Maven Central.
ccmvn
工具可让Maven在出站HTTPS被阻止或DNS解析不可用的受限沙箱环境中运行。它通过创建一个本地HTTP代理，供Maven访问Maven Central。

When to Use This Skill

适用场景

  • Running Maven builds (
    clean install
    , 
    package
    , 
    test
    , 
    compile
    , etc.)
  • Building Java projects that depend on Maven Central
  • Working in sandboxed environments with network restrictions
  • Needing to execute Maven with custom parameters and options
  • 运行Maven构建（
    clean install
    、
    package
    、
    test
    、
    compile
    等）
  • 构建依赖Maven Central的Java项目
  • 在存在网络限制的沙箱环境中工作
  • 需要使用自定义参数和选项执行Maven

Prerequisites

前置条件

Before using this skill, ensure:
  1. Maven is installed: The system must have Maven 3.x installed
  2. Node.js is available: Required for the proxy server (typically pre-installed in Claude Code)
  3. Proxy configuration (for sandboxed Claude Code): The 
    HTTPS_PROXY
    environment variable should be set if in a restricted sandbox
使用此技能前，请确保：
  1. 已安装Maven：系统必须安装Maven 3.x版本
  2. Node.js可用：代理服务器需要Node.js（Claude Code中通常已预装）
  3. 代理配置（针对沙箱环境下的Claude Code）：如果处于受限沙箱中，应设置
    HTTPS_PROXY
    环境变量

Basic Usage

基础用法

Simple Build

简单构建

```bash npx ccmvn clean install ```
bash
npx ccmvn clean install

Other Common Commands

其他常用命令

```bash
bash
undefined

Package the project

打包项目

npx ccmvn package
npx ccmvn package

Run tests

运行测试

npx ccmvn test
npx ccmvn test

Compile only

仅编译

npx ccmvn compile
npx ccmvn compile

Custom parameters

自定义参数

npx ccmvn clean install -DskipTests npx ccmvn clean install -X # Debug output ```
npx ccmvn clean install -DskipTests npx ccmvn clean install -X # 调试输出
undefined

How ccmvn Works

ccmvn工作原理

ccmvn creates a three-layer proxy chain:
``` Maven → Local Proxy → Upstream Sandbox Proxy → Maven Central (HTTP) (HTTP CONNECT) (HTTP/2 over TLS) ```
ccmvn会创建一个三层代理链：
Maven → 本地代理 → 上游沙箱代理 → Maven Central
       (HTTP)        (HTTP CONNECT)         (HTTP/2 over TLS)

Architecture Layers

架构分层

  1. Maven → Local Proxy (localhost:8080)
    • Plain HTTP communication
    • Maven configured via `~/.m2/settings.xml`
    • No authentication required locally
  2. Local Proxy → Upstream Proxy
    • HTTP CONNECT tunneling with JWT authentication
    • Upstream proxy performs DNS resolution for sandboxed environments
  3. Local Proxy → Maven Central
    • HTTP/2 over TLS with ALPN negotiation
    • Secure connection to Maven Central repositories
  1. Maven → 本地代理（localhost:8080）
    • 纯HTTP通信
    • 通过
      ~/.m2/settings.xml
      配置Maven
    • 本地无需认证
  2. 本地代理 → 上游代理
    • 带JWT认证的HTTP CONNECT隧道
    • 上游代理为沙箱环境执行DNS解析
  3. 本地代理 → Maven Central
    • 基于TLS的HTTP/2通信，支持ALPN协商
    • 与Maven Central仓库的安全连接

Automatic Configuration

自动配置

ccmvn automatically:
  • Creates `~/.m2/settings.xml` if it doesn't exist
  • Configures Maven to use the local proxy as a mirror for Maven Central
  • Starts the proxy server before running Maven
  • Cleans up the proxy server after Maven completes
ccmvn会自动完成以下操作：
  • 如果
    ~/.m2/settings.xml
    不存在则创建该文件
  • 配置Maven将本地代理用作Maven Central的镜像
  • 运行Maven前启动代理服务器
  • Maven完成后清理代理服务器

Common Maven Commands

常用Maven命令

CommandPurpose
`ccmvn clean`Remove build artifacts
`ccmvn compile`Compile source code
`ccmvn test`Run tests
`ccmvn package`Create JAR/WAR file
`ccmvn install`Install to local repository
`ccmvn deploy`Deploy to remote repository
`ccmvn clean install`Full clean build and install
命令用途
ccmvn clean
移除构建产物
ccmvn compile
编译源代码
ccmvn test
运行测试
ccmvn package
创建JAR/WAR文件
ccmvn install
安装到本地仓库
ccmvn deploy
部署到远程仓库
ccmvn clean install
完整清理构建并安装

Advanced Options

高级选项

Skip Tests During Build

构建时跳过测试

```bash npx ccmvn clean install -DskipTests ```
bash
npx ccmvn clean install -DskipTests

Run with Debug Output

启用调试输出运行

```bash npx ccmvn clean install -X ```
bash
npx ccmvn clean install -X

Specify Specific Goals

指定特定目标

```bash npx ccmvn clean compile test-compile ```
bash
npx ccmvn clean compile test-compile

Use Custom Settings File

使用自定义配置文件

Maven will automatically use `~/.m2/settings.xml`. To verify or modify proxy settings, check this file after running ccmvn.
Maven会自动使用
~/.m2/settings.xml
。若要验证或修改代理设置，请在运行ccmvn后检查该文件。

Troubleshooting

故障排查

Proxy Connection Issues

代理连接问题

If you see proxy-related errors:
  1. Ensure `HTTPS_PROXY` environment variable is correctly set (if in a sandboxed environment)
  2. Check that the proxy server can reach Maven Central
  3. Verify your proxy credentials are correct
如果遇到代理相关错误：
  1. 确保
    HTTPS_PROXY
    环境变量已正确设置（若处于沙箱环境）
  2. 检查代理服务器是否能连接到Maven Central
  3. 验证代理凭据是否正确

Maven Not Found

Maven未找到

If Maven is not installed: ```bash
若未安装Maven：
bash
undefined

Install Maven (varies by system)

安装Maven（根据系统不同而有所差异）

brew install maven # macOS apt-get install maven # Ubuntu/Debian ```
brew install maven # macOS apt-get install maven # Ubuntu/Debian
undefined

Maven Central Timeout

Maven Central超时

If builds timeout accessing Maven Central:
  1. Check your network connection
  2. Try again - temporary network issues can cause timeouts
  3. Use `-X` flag for debug output to see where it's hanging
如果构建时访问Maven Central超时：
  1. 检查网络连接
  2. 重试 - 临时网络问题可能导致超时
  3. 使用
    -X
    标志查看调试输出，确定卡顿时点

Settings.xml Issues

settings.xml问题

ccmvn automatically creates `~/.m2/settings.xml` if missing. If you have a custom settings file:
  1. Backup your current `~/.m2/settings.xml`
  2. Remove it and let ccmvn create a fresh one
  3. Or manually add the proxy mirror configuration
如果
~/.m2/settings.xml
缺失，ccmvn会自动创建。若你有自定义配置文件：
  1. 备份当前的
    ~/.m2/settings.xml
  2. 删除该文件，让ccmvn创建一个新的
  3. 或手动添加代理镜像配置

Examples

示例

Building a Spring Boot Application

构建Spring Boot应用

```bash npx ccmvn clean package -DskipTests ```
bash
npx ccmvn clean package -DskipTests

Running Unit Tests

运行单元测试

```bash npx ccmvn clean test ```
bash
npx ccmvn clean test

Full Build with All Checks

完整构建并执行所有检查

```bash npx ccmvn clean install ```
bash
npx ccmvn clean install

Building Specific Module (in multi-module project)

构建特定模块（多模块项目中）

```bash npx ccmvn clean install -pl module-name ```
bash
npx ccmvn clean install -pl module-name

Environment Variables

环境变量

HTTPS_PROXY (Sandboxed Environments Only)

HTTPS_PROXY（仅沙箱环境）

Format: `http://username:jwt_token@host:port\`
This is automatically used by ccmvn for sandboxed Claude Code environments. In local development, this is typically not needed.
格式：
http://username:jwt_token@host:port
ccmvn会自动在沙箱环境下的Claude Code中使用该变量。在本地开发中，通常不需要设置。

Security

安全说明

  • Local proxy only: The proxy server is only accessible on localhost
  • TLS validation: TLS certificates are validated for Maven Central
  • End-to-end encryption: Connection through the proxy chain maintains encryption
  • Token protection: JWT tokens are only used for authentication to the upstream proxy
  • 仅本地代理：代理服务器仅在localhost可访问
  • TLS验证：对Maven Central的TLS证书进行验证
  • 端到端加密：代理链中的连接保持加密
  • 令牌保护：JWT令牌仅用于向上游代理认证

Performance Tips

性能优化建议

  1. First build: Initial builds will download dependencies - this takes longer
  2. Incremental builds: Subsequent builds with cached dependencies are much faster
  3. Skip tests if not needed: Use `-DskipTests` to speed up builds during development
  4. Use clean install sparingly: Only use `clean` when you have problems or need a fresh build
  1. 首次构建：初始构建会下载依赖包 - 耗时较长
  2. 增量构建：后续使用缓存依赖的构建速度会快很多
  3. 无需测试时跳过：开发期间使用
    -DskipTests
    加快构建速度
  4. 谨慎使用clean install：仅在遇到问题或需要全新构建时使用
    clean

Resources

参考资源