Ubuntu 22.04 安装 Apache PyLucene 指南
在 Ubuntu 22.04 上从源码 0→1 构建安装 Apache PyLucene 9.12.0（JCC 预编译 + Gradle 构建 Lucene jar + make all），含 JDK/Python 版本匹配排障、wheel 离线分发与官方测试验证。
Ubuntu 22.04 安装 Apache PyLucene 指南
目标：在 Ubuntu 22.04 服务器上从零源码构建并安装 Apache PyLucene 9.12.0（Lucene 的 Python 绑定），覆盖依赖安装、JCC 预编译、Makefile 配置、Gradle 构建 Lucene jar、make all、官方测试套件验证与 wheel 离线分发，全部命令与回显均在 Ubuntu 22.04 实测通过。
一、环境信息
本章记录实测环境的软件版本。PyLucene 是 CPython 扩展模块，构建结果与 Python、JDK、GCC 版本强绑定，换任一版本都需要重新构建，因此安装前先固定环境。
cat /etc/os-release | head -2
python3 --version
java -version
ant -version
gcc --version | head -1
python3 -c "import setuptools; print('setuptools', setuptools.__version__)"
实测输出（Ubuntu 22.04 服务器）：
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
Python 3.10.12
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
Apache Ant(TM) version 1.10.12 compiled on January 17 1970
gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0
setuptools 59.6.0
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Python：3.10.12（系统自带，附 python3-dev 与 setuptools 59.6.0）
- JDK：OpenJDK 17.0.20.1（路径 /usr/lib/jvm/java-17-openjdk-amd64）
- 构建工具：Ant 1.10.12、GCC 11.4.0、make
- 实测版本组合：PyLucene 9.12.0 + JCC 3.14 + Lucene 9.12.0 + OpenJDK 17 + Python 3.10.12
- 实验目录：/root/build（源码下载与构建全部在该目录下）
💡 说明：JCC 与 PyLucene 必须使用同一个 JDK 构建（官方安装文档明确要求，升级 JDK 后须先重建 JCC）。本文所有构建命令都显式指向 /usr/lib/jvm/java-17-openjdk-amd64，避免多 JDK 机器上路径漂移。
二、前置条件
本章安装构建所需的系统软件包并确认 JDK 真实路径，这是后续所有步骤的地基。
apt-get update
apt-get install -y openjdk-17-jdk ant build-essential python3-dev python3-setuptools python3-pip wget curl unzip
实测输出（节选）：
Reading package lists... Done
Building dependency tree... Done
Setting up openjdk-17-jdk:amd64 (17.0.8.1+1~us1-0ubuntu1~22.04) ...
Setting up ant (1.10.12-6) ...
Setting up python3-dev (3.10.6-1~22.04) ...
确认 JDK 的 include 头文件与 JVM 库真实存在（JCC 编译链接要用到这两个目录）：
ls /usr/lib/jvm/java-17-openjdk-amd64/include/linux/jni.h
ls /usr/lib/jvm/java-17-openjdk-amd64/lib/server/libjvm.so
ls /usr/lib/jvm/java-17-openjdk-amd64/lib/libjava.so
实测输出：
/usr/lib/jvm/java-17-openjdk-amd64/include/linux/jni.h
/usr/lib/jvm/java-17-openjdk-amd64/lib/server/libjvm.so
/usr/lib/jvm/java-17-openjdk-amd64/lib/libjava.so
⚠️ 注意：JDK 9 及以上版本已取消
jre/子目录，libjava.so与libjvm.so分别位于lib/和lib/server/。JCC 自带的 setup.py 默认仍按 JDK 8 的jre/lib/amd64布局写路径，直接构建会链接失败——这是 PyLucene 在新 JDK 上最常见的第一道坎，修复方法见 4.4 节实测排障。
网络方面，若服务器访问国外源慢，可用代理（本文实测环境使用）：
export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
三、版本选型说明
PyLucene 版本号与 Lucene 完全同步，JDK 要求随 Lucene 主版本走。选择前先对照官方发行目录与各版本的 JDK 要求：
| PyLucene | 对应 Lucene | 发布日期 | JDK 要求 | Lucene 构建体系 |
|---|---|---|---|---|
| 10.0.0 | 10.0.0 | 2024-10-20 | Java 21+ | Gradle |
| 9.12.0 | 9.12.0 | 2024-10-11 | Java 11+ | Gradle |
| 9.4.1 | 9.4.1 | 2022-11-07 | Java 11+ | Gradle |
| 8.11.0 | 8.11.0 | 2021-12-15 | Java 8+ | Ant |
| 7.7.1 | 7.7.1 | 2019-03-18 | Java 8+ | Ant |
关键差异与如何选型：Ubuntu 22.04 官方仓库最高只有 openjdk-17，而 Lucene 10 要求 JDK 21，所以在不额外安装 JDK 的前提下 9.12.0 是当前平台的最新可用版本，也是本文实测通过的组合。另一个容易踩的坑：Lucene 从 9.x 起构建体系由 Ant 切换为 Gradle（实测源码包 CHANGES 记录"9.4.1 sources (now built with gradle)"），因此 PyLucene 9.x 构建时真正干活的是源码树自带的 Gradle wrapper，ant 仅旧版本（7.x/8.x）构建需要。
核实官方发行目录中的最新版本列表：
curl -s https://downloads.apache.org/lucene/pylucene/ | grep -oE 'pylucene-[0-9.]+-src.tar.gz' | sort -uV
实测输出：
pylucene-7.7.1-src.tar.gz
pylucene-8.11.0-src.tar.gz
pylucene-9.4.1-src.tar.gz
pylucene-9.12.0-src.tar.gz
pylucene-10.0.0-src.tar.gz
四、源码构建安装方案（A：官方主线）
4.1 方案说明
这是 PyLucene 官方安装文档给出的唯一正式安装方式，整体分四步：先构建安装 JCC（代码生成器），再编辑 Makefile 指定本机路径，然后 make all（内部先用 Gradle 构建内置 Lucene 源码产出 jar，再用 JCC 生成 C++ 包装并编译成 Python 扩展 wheel，最后 pip 安装），最后跑官方测试套件验证。全程约 30-50 分钟，其中 Gradle 首次下载依赖约 620MB、C++ 编译约 10 分钟。
4.2 下载与校验源码包
mkdir -p /root/build && cd /root/build
wget https://downloads.apache.org/lucene/pylucene/pylucene-9.12.0-src.tar.gz
sha256sum pylucene-9.12.0-src.tar.gz
实测输出（与官方 .sha256 文件内容一致，包完整）：
5d7223e87883e64ec0cd3e62a983a4bf50dce68c997081c8989e233b90cee115 pylucene-9.12.0-src.tar.gz
解压并确认目录结构：
tar xzf pylucene-9.12.0-src.tar.gz
ls pylucene-9.12.0/
实测输出：
CHANGES CREDITS INSTALL LICENSE Makefile NOTICE README
extensions jcc lucene-java-9.12.0 python samples test2 test3
jcc/：JCC 3.14 源码，第一步先构建它；lucene-java-9.12.0/：内置的 Lucene 9.12.0 完整源码树（含 Gradle wrapper）；samples/：官方 Python 示例（IndexFiles.py、SearchFiles.py 等）；test3/：Python 3 官方测试套件。
4.3 构建并安装 JCC（含实测排障）
JCC 是把 Java 类生成 CPython C++ 扩展的代码生成器，PyLucene 发行包自带配套版本，必须先安装且处于 shared 模式（Linux 上 setuptools ≥ 58.3 时自动启用）。先修改 jcc/setup.py 中 Linux 平台的 JDK 路径（默认指向 temurin-17，改为系统 openjdk-17）：
cd /root/build/pylucene-9.12.0/jcc
sed -i "s#'linux': '/usr/lib/jvm/temurin-17-jdk-amd64'#'linux': '/usr/lib/jvm/java-17-openjdk-amd64'#" setup.py
grep -n "'linux': '/usr/lib/jvm" setup.py
实测输出：
74: 'linux': '/usr/lib/jvm/java-17-openjdk-amd64',
第一次构建——真实失败路径。直接构建会在链接阶段报错：
python3 setup.py build
实测输出（关键行）：
x86_64-linux-gnu-g++ -shared ... -o build/lib.linux-x86_64-3.10/libjcc3.so
-L/usr/lib/jvm/java-17-openjdk-amd64/jre/lib/amd64 -ljava
-L/usr/lib/jvm/java-17-openjdk-amd64/jre/lib/amd64/server -ljvm ...
/usr/bin/ld: cannot find -ljava: No such file or directory
/usr/bin/ld: cannot find -ljvm: No such file or directory
collect2: error: ld returned 1 exit status
error: command '/usr/bin/x86_64-linux-gnu-g++' failed with exit code 1
定位：报错里的搜索路径是 jre/lib/amd64，这是 JDK 8 的目录布局；JDK 17 里 libjava.so 在 lib/、libjvm.so 在 lib/server/（见 4.1 节验证命令）。修复 setup.py 中 linux/x86_64 的链接参数，把 jre/lib/amd64 全部替换为 lib：
python3 - <<'EOF'
p = 'setup.py'
s = open(p).read()
old = """ 'linux/x86_64': ['-L%(linux)s/jre/lib/amd64' %(JDK), '-ljava',
'-L%(linux)s/jre/lib/amd64/server' %(JDK), '-ljvm',
'-Wl,-rpath=%(linux)s/jre/lib/amd64:%(linux)s/jre/lib/amd64/server' %(JDK)],"""
new = """ 'linux/x86_64': ['-L%(linux)s/lib' %(JDK), '-ljava',
'-L%(linux)s/lib/server' %(JDK), '-ljvm',
'-Wl,-rpath=%(linux)s/lib:%(linux)s/lib/server' %(JDK)],"""
assert old in s, 'pattern not found'
open(p, 'w').write(s.replace(old, new))
print('setup.py patched OK')
EOF
实测输出：
setup.py patched OK
第二次构建——成功路径：
python3 setup.py build 2>&1 | tail -2
python3 setup.py install 2>&1 | tail -4
实测输出：
x86_64-linux-gnu-g++ -shared ... -o build/lib.linux-x86_64-3.10/jcc/_jcc3.cpython-310-x86_64-linux-gnu.so
-L/usr/lib/jvm/java-17-openjdk-amd64/lib -ljava
-L/usr/lib/jvm/java-17-openjdk-amd64/lib/server -ljvm ...
Extracting JCC-3.14-py3.10-linux-x86_64.egg to /usr/local/lib/python3.10/dist-packages
Adding JCC 3.14 to easy-install.pth file
Installed /usr/local/lib/python3.10/dist-packages/JCC-3.14-py3.10-linux-x86_64.egg
验证 JCC 安装结果与 shared 模式（PyLucene 构建的硬性要求）：
python3 -c "from jcc import config; print('JCC VERSION:', config.VERSION); print('SHARED:', config.SHARED); print('LFLAGS:', config.LFLAGS)"
python3 -m jcc --help | head -4
实测输出：
JCC VERSION: 3.14
SHARED: True
LFLAGS: ['-L/usr/lib/jvm/java-17-openjdk-amd64/lib', '-ljava', '-L/usr/lib/jvm/java-17-openjdk-amd64/lib/server', '-ljvm', '-Wl,-rpath=/usr/lib/jvm/java-17-openjdk-amd64/lib:/usr/lib/jvm/java-17-openjdk-amd64/lib/server']
JCC - C++/Python Java Native Interface Code Generator
Usage: python -m jcc [options] [actions] classes...
SHARED: True 说明 shared 模式已自动启用；LFLAGS 中的 rpath 指向 JDK 17 真实库目录。
4.4 编辑 Makefile
Makefile 需要按本机环境取消注释并填写一个 Linux 段。在 # Linux (Debian Bullseye ...) 注释段后插入 Ubuntu 22.04 专用配置：
cd /root/build/pylucene-9.12.0
python3 - <<'EOF'
p = 'Makefile'
s = open(p).read()
anchor = "#NUM_FILES=16\n"
add = """
# Linux (Ubuntu 22.04 64-bit, Python 3.10.12, OpenJDK 17)
PREFIX_PYTHON=/usr
ANT=/usr/bin/ant
PYTHON=$(PREFIX_PYTHON)/bin/python3
JCC=$(PYTHON) -m jcc --shared
NUM_FILES=16
MODERN_PACKAGING=true
"""
# 只在 Debian Bullseye 示例段（首个未注释 Linux 段之前）后插入
i = s.index(anchor)
s = s[:i + len(anchor)] + add + s[i + len(anchor):]
open(p, 'w').write(s)
print('Makefile patched OK')
EOF
实测输出：
Makefile patched OK
各变量含义（实测取值）：
| 变量 | 实测值 | 说明 |
|---|---|---|
| PREFIX_PYTHON | /usr | Python 安装前缀，Ubuntu 系统自带的 python3 在 /usr/bin 下 |
| PYTHON | /usr/bin/python3 | 参与构建的 Python 解释器 |
| ANT | /usr/bin/ant | ant 路径；9.x 构建实际走 Gradle，此变量仅为兼容旧目标保留 |
| JCC | $(PYTHON) -m jcc --shared | JCC 调用方式，--shared 必须保留 |
| NUM_FILES | 16 | 生成的 C++ 包装文件分片数，分片可绕过编译器单文件大小限制 |
| MODERN_PACKAGING | true | setuptools ≥ 58.3 时必须开启（本机 59.6.0），构建改用 build/wheel 流程 |
⚠️ 注意：setuptools ≥ 58.3.0 的环境若忘开
MODERN_PACKAGING=true，make 会走旧的 setup.py install 分支并报 setup.py 命令不支持类错误；setuptools < 58.3 则不能开启。以python3 -c "import setuptools; print(setuptools.__version__)"的实测值决定。
4.5 构建 Lucene 运行时 jar（Gradle 阶段）
make all 的第一步是进入内置 Lucene 源码树执行 ./gradlew collectRuntimeJars，首次运行会下载 Gradle 发行版与全部 Maven 依赖（约 620MB，落盘在 ~/.gradle）。这一步独立演示并计时：
cd /root/build/pylucene-9.12.0
make lucene
实测输出（节选，Gradle 汇总 124 个任务；make lucene 整步实测数分钟，主要耗时在首次下载 Gradle 8.10 发行版与约 620MB Maven 依赖）：
(cd lucene-java-9.12.0; ./gradlew collectRuntimeJars)
Downloading https://services.gradle.org/distributions/gradle-8.10-bin.zip ........
> Task :lucene:core:compileJava
> Task :lucene:analysis:common:compileJava
BUILD SUCCESSFUL in 2m 29s
124 actionable tasks: 124 executed
验证 runtime jar 产物：
ls lucene-java-9.12.0/lucene/core/build/runtimeJars/
find lucene-java-9.12.0 -path '*build/runtimeJars/*.jar' | wc -l
实测输出：
lucene-core-9.12.0-SNAPSHOT.jar
72
lucene-core-9.12.0-SNAPSHOT.jar 等 72 个运行时 jar 已生成（SNAPSHOT 后缀是 Gradle 源码构建的正常命名，JCC 包装时按此路径引用）。
4.6 make all：生成、编译、安装
再次执行 make all（Gradle 部分已缓存，秒级完成；随后 JCC 生成 16 个 C++ 包装文件并编译，最后 pip 安装 wheel）：
cd /root/build/pylucene-9.12.0
make all
实测输出（节选，完整日志约 1 万行）：
ICU not installed
/usr/bin/python3 -m jcc --shared --jar lucene-java-9.12.0/lucene/core/build/runtimeJars/lucene-core-9.12.0-SNAPSHOT.jar --jar ... --use_full_names ... --python lucene --version 9.12.0 ... --files 16 --generate
x86_64-linux-gnu-gcc -Wno-unused-result ... -c build/_lucene/__wrap01__.cpp -o build/temp.linux-x86_64-3.10/build/_lucene/__wrap01__.o ...
/usr/bin/python3 -m build -nw
Successfully built lucene-9.12.0-cp310-cp310-linux_x86_64.whl
/usr/bin/python3 -m pip install dist/lucene-9.12.0-cp310-cp310-linux_x86_64.whl --force-reinstall
Successfully installed lucene-9.12.0
build of pylucene 9.12.0 complete
关键环节解读：
--jar ...24 个运行时 jar 逐个传给 JCC 生成 Python 包装（--python lucene指定模块名，--version 9.12.0）；ICU not installed是可忽略提示（ICU 分析器属可选模块，未启用时跳过其资源处理）；python3 -m build -nw把生成的 setup.py 编成 wheel（-n 不隔离、-w 只出 wheel）；- wheel 约 42MB，pip 安装到 /usr/local/lib/python3.10/dist-packages/lucene/。
查看产物与安装位置：
ls -la dist/
python3 -c "import lucene; print(lucene.__file__); print(lucene.VERSION)"
实测输出：
-rw-r--r-- 1 root root 42294544 Oct 16 04:16 lucene-9.12.0-cp310-cp310-linux_x86_64.whl
/usr/local/lib/python3.10/dist-packages/lucene/__init__.py
9.12.0
4.7 make test：官方测试套件验证
PyLucene 自带 Python 3 测试套件（test3/ 下 13 个测试文件），make test 会先重装 wheel 再逐个运行：
cd /root/build/pylucene-9.12.0
make test
实测输出（节选汇总）：
/usr/bin/python3 -m pip install dist/lucene-9.12.0-cp310-cp310-linux_x86_64.whl --force-reinstall
Processing ./dist/lucene-9.12.0-cp310-cp310-linux_x86_64.whl
Installing collected packages: lucene
...
Ran 18 tests in 0.389s
OK
Ran 11 tests in 1.838s
OK
...
统计全部测试结果：
grep -c "Ran .* tests" /root/make_test.log
grep -c "^OK" /root/make_test.log
grep -cE "FAILED|Traceback" /root/make_test.log
grep "Ran " /root/make_test.log | awk '{s+=$2} END {print "total tests:", s}'
实测输出：
13
27
0
total tests: 127
13 个测试文件、127 个用例、27 个 OK 汇总、0 个失败，官方测试全部通过——这是"构建成功"的最硬证据。
4.8 安装结果验证
用最小代码验证 Python → JCC → 内嵌 JVM 三层连通（完整建索引/检索示例见《Apache PyLucene 常用 CLI 命令与工具详解》）：
python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m'])
from java.lang import System
System.out.println('java.version = ' + System.getProperty('java.version'))
print('PyLucene JVM init OK')
"
实测输出：
java.version = 17.0.20.1
PyLucene JVM init OK
JVM 堆内存限制也一并验证（PyLucene 的 JVM 参数在 initVM 的 vmargs 里传，不走环境变量；见《Apache PyLucene 配置与构建参数详解》）：
python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m'])
from java.lang import Runtime
print('maxMemory(MB):', int(Runtime.getRuntime().maxMemory()/1024/1024))
"
实测输出：
maxMemory(MB): 256
五、wheel 离线分发安装方案（B：备用）
5.1 方案说明
PyLucene 在 PyPI 上没有官方预编译包，但对"多台同配置服务器"场景，可以把方案 A 构建出的 wheel 直接分发离线安装，目标机无需再走 40 分钟构建。前提：目标机为同架构（x86_64）、同 Python 小版本（cp310）且 JDK 安装路径一致（扩展库 rpath 硬编码了 /usr/lib/jvm/java-17-openjdk-amd64）。
5.2 分发与安装步骤
把 wheel 拷贝到目标机任意目录后安装（本节在同一台机器上实测该流程）：
python3 -m pip install /root/build/pylucene-9.12.0/dist/lucene-9.12.0-cp310-cp310-linux_x86_64.whl --force-reinstall
实测输出（wheel 产物已在 4.6 节确认过）：
Processing ./dist/lucene-9.12.0-cp310-cp310-linux_x86_64.whl
Installing collected packages: lucene
Successfully installed lucene-9.12.0
python3 -c "import lucene; print('lucene VERSION:', lucene.VERSION)"
实测输出：
lucene VERSION: 9.12.0
⚠️ 注意：wheel 内含 .so 动态库，只适用"同 Python 小版本 + 同 JDK 路径 + 同架构"的目标机；三者任一不同都必须在目标机重新源码构建。JCC 本身也需在目标机安装（同版本 JDK 重建，见 4.3 节）。
六、方案对比与选择建议
| 维度 | 方案 A：源码构建 | 方案 B：wheel 离线分发 |
|---|---|---|
| 耗时 | 约 30-50 分钟（含 Gradle 下载 620MB） | 分钟级 |
| 网络要求 | 需访问 Apache/Maven/Gradle 源 | 完全离线 |
| 环境一致性 | 可适配任意 Python/JDK 组合 | 必须与构建机三同（架构/Python/JDK 路径） |
| 可复现性 | 高（每次源码构建） | 依赖构建机产物留存 |
| 适用场景 | 首次安装、环境非标、升级版本 | 批量同构服务器铺开 |
如何选型：第一台服务器（或版本/环境变化时）必须走方案 A 拿到验证过的 wheel；其余同构服务器用方案 B 铺开，是实测下来兼顾可靠性与效率的做法。
七、配置说明
PyLucene 装完即用，没有独立的配置文件，但有三个环境级配置项需要了解：
- JVM 参数：在每次
lucene.initVM(vmargs=[...])里传（如-Xmx256m），不是环境变量。JVM 全局只初始化一次，后续 initVM 调用只是附加线程；生产建议 256-512MB 起步并实测确认（4.8 节已验证 maxMemory=256MB）。 - CLASSPATH 限制：运行期无法给内嵌 JVM 追加 classpath（老版
lucene.addClasspath已不存在，vmargs 传-Djava.class.path实测直接 SIGSEGV）；要使用未打包的 Lucene 模块，只能构建期改 Makefile JARS 后重新 make，实测结论见《Apache PyLucene 配置与构建参数详解》§5.3。 - 代理环境变量：构建期 Gradle 走 JVM 系统属性（
GRADLE_OPTS="-Dhttps.proxyHost=... -Dhttps.proxyPort=..."），不走 http_proxy 环境变量；pip/wget 走标准http_proxy/https_proxy。
八、常见问题（FAQ）
Q1：JCC 构建报 cannot find -ljava/-ljvm 怎么办？
JDK 9+ 取消了 jre/ 目录，setup.py 还按 JDK 8 布局找库。按 4.3 节把 linux/x86_64 的 LFLAGS 改为 -L$(JDK)/lib 与 -L$(JDK)/lib/server（含 rpath），重新 setup.py build 即可，实测通过。
Q2：make 报 setuptools 相关错误或 setup.py install 不被支持？
setuptools ≥ 58.3 必须在 Makefile 开 MODERN_PACKAGING=true，并 python3 -m pip install build wheel 提前装好构建后端（本机 setuptools 59.6.0 实测开启后构建正常）。
Q3：make all 在 setup.py 目标报 NoClassDefFoundError: org/locationtech/spatial4j/shape/ShapeFactory？
自己往 Makefile 的 JARS 里加了 SPATIAL_EXTRAS_JAR 导致。spatial-extras 依赖外部库 spatial4j-0.8.jar（在其 runtimeJars 目录里但不在 JCC 的 classpath 上），官方默认注释该行正是这个原因。除非把 spatial4j 加进 GENERATE 的 --include，否则不要启用该行。
Q4：启用 smartcn 后构建报 Can not find lexical dictionary directory？
JCC 包装阶段装载 org.apache.lucene.analysis.cn.smart.AnalyzerProfile，其静态初始化在当前目录找不到 analysis-data 目录就抛 RuntimeException 中断构建。实测修复（两处）：
mkdir -p /root/analysis-data
make all JCCFLAGS="--vmarg -Danalysis.data.dir=/root/analysis-data"
同时运行期 initVM 也要传同一属性：lucene.initVM(vmargs=['-Danalysis.data.dir=/root/analysis-data'])。词库主数据已内嵌在 jar 里（classpath 加载），该属性指向空目录即可。实测修复后构建与中文分词均正常。
Q5：构建时 Gradle 下载依赖很慢或失败？ Gradle 不读 http_proxy 环境变量，走 JVM 系统属性：
export GRADLE_OPTS="-Dhttps.proxyHost=192.168.1.62 -Dhttps.proxyPort=7897 -Dhttp.proxyHost=192.168.1.62 -Dhttp.proxyPort=7897"
make lucene
依赖落盘在 ~/.gradle（实测 620MB），二次构建直接命中缓存（BUILD SUCCESSFUL in 8s）。
Q6：import lucene 后 initVM 报 JVM 已存在或崩溃（SIGSEGV）？
JVM 在一个 Python 进程里只能初始化一次，重复 initVM 会抛错；而 vmargs 不一致或 libjvm 加载失败可能触发底层崩溃。每个进程只 initVM 一次，多线程用 with lucene.attachThread(): 包裹，不要在子进程里 fork 后继续用 JVM（Python 多进程场景每进程各自 initVM）。
Q7：升级了 Python 或 JDK 之后原来的 lucene 模块不能用了？ CPython 扩展按解释器 ABI（cp310）编译、按 JDK 路径（rpath）链接，二者任一变化都必须重建 JCC 和 PyLucene（官方要求 JCC 与 PyLucene 同一 JDK）。重新走第四章流程即可，Gradle 缓存可复用。
九、卸载与清理
卸载 Python 包与 JCC，删除构建目录和缓存：
python3 -m pip uninstall -y lucene
实测输出：
Found existing installation: lucene 9.12.0
Uninstalling lucene-9.12.0:
Successfully uninstalled lucene-9.12.0
rm -rf /usr/local/lib/python3.10/dist-packages/JCC-3.14-py3.10-linux-x86_64.egg
sed -i '/JCC-3.14/d' /usr/local/lib/python3.10/dist-packages/easy-install.pth
rm -rf /root/build/pylucene-9.12.0 /root/.gradle
若只是想释放磁盘，可只删 ~/.gradle（620MB 依赖缓存）与源码树，保留已安装的 lucene 模块继续使用。
十、参考链接
- PyLucene 官方构建文档：https://lucene.apache.org/pylucene/install.html
- 官方发行包目录（含 sha256）：https://downloads.apache.org/lucene/pylucene/
- JCC 安装说明：https://lucene.apache.org/pylucene/jcc/install.html
- PyLucene 版本时间线：https://lucene.apache.org/pylucene/news.html
- Lucene 9.12 系统要求：https://lucene.apache.org/core/corenews.html
- 选型背景参考《Apache PyLucene 介绍与选型指南》