简介：面向 Eclipse/MyEclipse 开发者的 SVN 版本控制插件包，对应 site-1.8.22 稳定分支，重点解决在 IDE 内直接完成代码提交、更新、历史查看与冲突处理等需求，适合需要将项目纳入 SVN 协作流程的初中级 Java 开发人员及团队维护者。压缩包共 30 个文件、约 16.9MB，以 27 个 jar 插件组件为主体，辅以 docx 安装说明、xml 站点描述和 html 帮助入口，覆盖插件运行库、功能特性与部署指引，便于在 MyEclipse 10 中按文档完成离线安装。已有 940 人学习下载。使用者可借助配套文档理解站点更新源的配置方式，并利用提交、更新、差异对比、版本日志、回滚与冲突合并等能力，在 IDE 内完成日常版本管理；对需要固定 1.8.x 客户端版本、排查插件依赖或搭建旧版开发环境的读者也具有参考价值。

1. 内网 Eclipse 装不上 SVN 插件时，site-1.8.22 这个离线包能省掉一下午

在内网机器上给 Eclipse 配 svn插件，最耗时间的环节基本不在“下一步”，而在更新站点那条进度条一直停在 0%。site-1.8.22 这类离线站点包就是为这个场景准备的：它是一个已经打包好的插件更新站点目录，里面是 features、plugins 加上站点元数据，配着随包的 svn安装说明，解压后把安装向导指向本地路径就能装完，全程不碰外部更新站点。适合三类人：守着隔离网段开发机的维护者、要给一批机器统一装同一套 svn插件 的人，以及手上还留着老版本 Eclipse、却必须接 SVN 仓库继续干活的人。它解决的是“装不上”，不是“不好用”，这个边界一开始就要认清。

2. 拆开 site-1.8.22：features、plugins 与元数据各自管什么

2.1 site 包和普通插件 jar 的区别

很多人第一次拿到这个包会愣一下：解压出来一堆目录，找不到一个能双击的 exe，也找不到熟悉的“安装”字样。原因在于 site 包不是插件本身，而是一个更新站点的快照。单个插件是一个 bundle jar，扔进 plugins 目录就能跑；而站点包描述的是一组 bundle 及其依赖关系，Eclipse 的 p2 安装器要先读元数据、算依赖、再决定复制哪些文件。跳过元数据这一步直接把 jar 拷进去，能不能成完全看运气——这正是同一个包有人一次装好、有人反复失败的根本原因。

解压之后大致会遇到下面这几类内容，对照着看，心里就有数了：

这里有个容易忽略的点：content.jar和content.xml是同一份内容的不同封装，前者是压缩过的。老包可能只有site.xml，新包基本只有 p2 元数据。判断依据很简单，看根目录下哪个文件存在，后面的安装路径选择就跟着它走。

2.2 三步自检：完整性、结构、依赖声明

动手装之前先花两分钟做三件事，能挡掉后面一大半莫名其妙的问题。第一步确认包没在传输过程中被截断，内网拷贝、邮件中转、网盘下载都可能出这种事：

# 步骤 1：校验完整性，确认压缩包没有在传输中被截断 sha1sum site-1.8.22.zip unzip -l site-1.8.22.zip | tail -n 3

sha1sum的结果要和来源方给出的校验值逐位比对，对不上就别往下走了，直接重新拿包。unzip -l最后一行的条目总数是个粗略指标，如果只有十几个条目，而目录表里明显应该有几十个 jar，基本可以判定包是残缺的。

第二步解压到独立目录。这一步别偷懒直接解压进 Eclipse 安装目录，否则污染了也说不清是谁干的：

# 步骤 2：解压到独立目录，避免污染 Eclipse 安装目录 SITE=~/svn-plugin/site-1.8.22 mkdir -p "$SITE" unzip -q site-1.8.22.zip -d "$SITE" find "$SITE" -maxdepth 2 -type d | sort

-d指定解压目标，-q只是静默输出。find -maxdepth 2 -type d是这一步的重点：不少压缩包会多套一层同名目录，解压出来变成site-1.8.22/site-1.8.22/features。这个多出来的一层会让后面所有路径都错位，先看清结构再往下走，比事后排查省事得多。

第三步看 bundle 声明。这一步决定了两件事：你在安装详情里该搜什么关键字，以及这个插件当初是按什么运行环境编译的：

# 步骤 3：列出 bundle 名与编译目标运行环境 ls "$SITE"/plugins/*.jar | wc -l for j in "$SITE"/plugins/*.jar; do unzip -p "$j" META-INF/MANIFEST.MF 2>/dev/null \ | grep -E '^(Bundle-SymbolicName|Bundle-Version|Bundle-RequiredExecutionEnvironment)' \ | sed "s|^|$(basename "$j"): |" done | head -n 40

unzip -p把 jar 内文件直接输出到标准输出，不落盘，适合这种“只看不改”的检查。Bundle-SymbolicName是 bundle 的唯一标识，记住带svn或subversion字样的那几个，后面验证安装是否生效全靠它们；Bundle-RequiredExecutionEnvironment是编译目标，取值形如J2SE-1.5、JavaSE-1.6这种。这一项如果比你当前运行的 JDK 老出一大截，说明插件是上一个时代的产物——能不能装上是一回事，装上之后某些 API 行为对不上是另一回事，第 4 章会细说这条边界。head -n 40只是防止输出刷屏，真排查的时候应该全量看完。

2.3 随包安装说明里最容易被跳过的两句

说明文档通常不长，但有两类信息几乎每次都被跳过去。第一类是适用版本区间，往往写成“适用于 Eclipse 3.x / 4.x 早期版本”这种模糊表述，或者干脆只写了当年打包时的 IDE 版本号。第二类是“安装完成后需以 clean 模式重启一次”。后面这句不是客套话，p2 的 bundle 缓存不重建，插件装了也白装，界面该没有还是没有。我的习惯是先把说明通读一遍，把它声称的适用版本记下来，再去核对当前环境的实际版本，对不上就提前想好退路，而不是装到一半才发愁。

3. 三条落地安装路径：快照、本地站点、dropins 投放

3.1 先做安装前快照，这是唯一的后悔药

Eclipse 插件安装最麻烦的地方不在装，在于装坏了怎么退。通过 p2 安装的还能在安装详情里卸载，手工拷进去的只能靠记忆删，而记忆通常不可靠。所以不管走哪条路径，第一步永远是打快照：

#!/usr/bin/env bash # eclipse-plugin-snapshot.sh # 用途：记录 Eclipse 安装目录下 features/plugins/dropins 的清单 # 用法：./eclipse-plugin-snapshot.sh /opt/eclipse before.txt set -euo pipefail ECLIPSE_HOME="${1:?用法: $0 <eclipse安装目录> <输出文件>}" OUT="${2:?缺少输出文件路径}" { echo "== features ==" find "$ECLIPSE_HOME/features" -maxdepth 1 -name '*.jar' -printf '%f\n' | sort echo "== plugins ==" find "$ECLIPSE_HOME/plugins" -maxdepth 1 -name '*.jar' -printf '%f\n' | sort echo "== dropins ==" find "$ECLIPSE_HOME/dropins" -maxdepth 2 -printf '%P\n' 2>/dev/null | sort } > "$OUT" wc -l "$OUT"

安装前跑一次输出before.txt，安装后跑一次输出after.txt，diff -u before.txt after.txt一眼就能看出到底多了哪几个 jar。参数上只有两个位置参数，第一个是 Eclipse 安装根目录，第二个是输出文件名，脚本里用了set -euo pipefail，路径写错会立刻报错而不是静默生成一个空文件——空文件比报错更坑，你以为快照成功了，回滚的时候才发现什么都没有。

提示：find -printf是 GNU find 的扩展，macOS 自带的是 BSD find，需要装 gfind 或改用-exec basename {} \;。这类小差异在跨平台团队里最容易翻车。

有了这份 diff，回滚就是rm掉多出来的那几个 jar 再加-clean重启，五分钟的事。

3.2 路径 A：Install New Software 指向本地站点目录

这是最正统的一条路，也是唯一能把依赖关系算清楚的路径。操作链路是：Help → Install New Software → Add → Local，然后在目录选择框里指向解压出来的目录。这里有个关键判断——指向哪一层。如果根目录下有content.jar或artifacts.jar，就指向根目录；如果根目录只有site.xml，新版 Eclipse 可能读不出来，这时改用 Archive 方式直接选那个 zip 文件，让 p2 自己去解。

选对目录之后，中间那块列表会列出可安装的条目。如果列表是空的，说明层级选错了或元数据缺失，退回上一级或下一级再试，不要在这一步反复纠结，换一层往往就出来了。勾选条目、一路 Next、接受许可、重启，这是标准流程。

装完的验证方法比安装本身更重要：Help → About → Installation Details → Plugins 标签页，在搜索框里敲svn或subversion，看第 2 章记下来的那些 bundle 名是否都在。在，说明 p2 层面注册成功；不在，说明列表里显示的成功只是文件拷过去了，依赖没解析。

注意：这条路径装出来的插件可以用 Uninstall 卸载，回滚成本最低。只要情况允许，优先走它。

3.3 路径 B：dropins 投放，适合批量分发

要给一批机器装同一套东西，一台台点安装向导不现实。dropins 目录就是为分发设计的：Eclipse 启动时会扫描这个目录，把里面的插件合并进来。

# 路径 B：把整个站点投放进 dropins，适合批量分发 ECLIPSE_HOME=/opt/eclipse SITE=~/svn-plugin/site-1.8.22 mkdir -p "$ECLIPSE_HOME/dropins/svn-1.8.22" cp -r "$SITE"/. "$ECLIPSE_HOME/dropins/svn-1.8.22/" # 投放完成后必须带 -clean 冷启动一次 "$ECLIPSE_HOME"/eclipse -clean

cp -r "$SITE"/.里的那个点很关键，它表示复制目录内容而不是目录本身，少写这个点就会变成dropins/svn-1.8.22/site-1.8.22/features，多出一层，p2 扫不到。放进 dropins 的目录建议用版本号命名，将来同时存在两版的时候，删哪个一目了然。

-clean这个参数的作用是让 p2 清掉缓存重新扫描，代价是启动慢一次，之后就正常了。批量分发时我一般会写一个简单的 shell 脚本，把拷贝和首次启动串起来，让使用者只需要执行一条命令。

3.4 路径 C：手工复制 features 和 plugins，兜底方案

前两条路都走不通——比如老站点包在新 IDE 上元数据解析失败——就只剩手工复制。这条路能装上的概率不低，但依赖关系完全没人管，装完出问题的概率也最高，属于兜底而不是首选。

# 路径 C：手工复制，仅在前两条路径都失败时使用 ECLIPSE_HOME=/opt/eclipse SITE=~/svn-plugin/site-1.8.22 # 先快照，再动手 ./eclipse-plugin-snapshot.sh "$ECLIPSE_HOME" before.txt cp -v "$SITE"/features/*.jar "$ECLIPSE_HOME/features/" cp -v "$SITE"/plugins/*.jar "$ECLIPSE_HOME/plugins/" # 重建缓存 "$ECLIPSE_HOME"/eclipse -clean

-v让每个被复制的文件都打印出来，出问题时这份输出就是最直接的证据。复制完不要急着开 IDE 干活，先按 3.2 里的验证方法搜一遍 bundle 名，确认注册上了再往下。

如果复制时报文件名冲突，说明目标目录里已经有同名同版本的 bundle。这种情况下别覆盖，先ls看版本号，同版本就是重复了，跳过即可；不同版本同时存在会引发“到底加载哪一个”的玄学问题，宁可删掉旧的也不要两版并存。

三条路径的取舍其实很简单：能联网解析依赖就走 A，要批量就走 B，前两条都堵死了才用 C。顺序反了，后面排查成本会翻好几倍。

4. 版本对齐：插件 1.8.22、IDE 运行环境与工作副本格式

4.1 三个互相独立的版本维度

新手最容易犯的错，是把“插件版本 1.8.22”当成一个能代表全部信息的数字，然后拿它去和服务端版本直接对比。实际上这里至少有三个互相独立的维度：插件自身的版本号、插件内置的 SVN 实现库版本、以及 SVN 服务端与工作副本格式。三者各自演进，任何一对错配都会表现出不同的症状。

第一条边界是插件版本和 IDE 版本。1.8.22 这个编号本身就说明它是一个有年头的包，当年配套的 IDE 是 Eclipse 3.x 到 4.x 早期那一代。把它装到近几年的 IDE 上，最常见的结局是安装向导里直接报依赖缺失，提示某个 bundle 的版本区间不满足。这种情况下强行手工复制，装是能装上，但启动日志里会冒出一堆NoClassDefFoundError之类的报错，功能界面出不来。

第二条边界是插件和 JDK。第 2 章里读到的Bundle-RequiredExecutionEnvironment就是这条边界的证据。编译目标是J2SE-1.5的 bundle，运行在 JDK 17 上，轻则反射调用被模块系统挡住，重则类加载失败。这条边界不像第一条那么显性，往往表现为“界面出来了，但某个操作莫名失败”，排查起来最费劲。

第三条边界是工作副本格式，这个下面单独讲，因为它是唯一一条升级之后就回不去的边界。

4.2 用 MANIFEST 判断兼容性，而不是猜

与其凭经验猜“这个版本应该能装”，不如直接读依赖声明。下面这条命令会把每个 bundle 的导入包和必需 bundle 都列出来：

# 查看 bundle 的依赖声明，判断能否在当前 IDE 上解析 SITE=~/svn-plugin/site-1.8.22 for j in "$SITE"/plugins/*.jar; do echo "=== $(basename "$j") ===" unzip -p "$j" META-INF/MANIFEST.MF 2>/dev/null \ | sed -n '/^Require-Bundle:/,/^[A-Z]/p' \ | head -n 10 done

sed -n '/^Require-Bundle:/,/^[A-Z]/p'的作用是截取从Require-Bundle开始、到下一个大写字母开头的头部字段为止的区间，因为 MANIFEST 的续行以空格开头，这样截才能拿到完整的一条声明。看到形如org.eclipse.ui,3.5.0这样的写法，意思是需要 UI 组件且版本不低于 3.5.0；如果你的 IDE 里这个 bundle 已经是 3.2x，版本区间通常还能满足，但如果声明里带了上界（,3.5.0)这种带右括号的写法），超了就会被拒绝。

实际排查时不需要把所有 bundle 都看一遍，只盯那个名字里带ui或core的主 bundle 就够了，依赖链通常由它牵头。

4.3 工作副本格式：一次升级就回不去的那道坎

SVN 的工作副本格式是跟着客户端版本走的，业界通行的对应关系是：1.7 系列对应格式 29，1.8 系列对应格式 31。一旦某个更高版本的客户端在某份工作副本上执行过写操作，格式就被就地升级了，之后低版本客户端打开它只会得到一句“工作副本格式不被支持”。

这条规则对插件同样适用。插件内置的 SVN 实现库决定了它认识哪一档格式，而这个库的版本和插件自身版本号并不总是一致。判断方法是在 IDE 的插件首选项里找 SVN 相关页面，看它列出的接口实现和版本信息，与团队成员用的命令行客户端版本对一遍。对不上，就会出现你更新完别人提交不了、或者别人更新完你这边满屏红叉的局面。

处理策略只有两条，没有第三条：要么统一全组客户端版本，只升不降；要么给需要兼容老版本的人单独 checkout 一份新工作副本，别在原来那份上继续操作。我一般倾向于前者，代价是升级那天全组停摆半小时，但省掉了后面无数次“为什么只有你这台机器有问题”的对话。

5. 避坑与排查：装完不生效、图标不出现、提交报错

5.1 五条踩坑记录，每条都能对上号

坑一：安装向导一路成功，重启后界面里什么都没有。现象是安装流程走完、提示重启，重启完在透视图列表里翻不到任何跟 SVN 相关的东西。原因是 p2 的 bundle 缓存没重建，文件确实拷进去了，但运行时配置里没登记。解决办法是带-clean参数冷启动一次，并且去configuration/org.eclipse.equinox.simpleconfigurator/bundles.info里搜一下 bundle 名，搜不到就说明注册这一步根本没发生，需要回到 3.2 重装一遍而不是继续重启。

坑二：Add Local 之后提示 No repository found。现象是本地目录明明选对了，向导却说不认识这个仓库。九成是把目录层级指错了——指到了包含 site 目录的上一层，或者指到了解压时多套的那一层。解决办法是从当前目录往上、往下各试一层，找那个直接含content.jar、artifacts.jar或site.xml的目录；如果包里只有site.xml而 IDE 版本较新，改用 Archive 方式直接选 zip 文件，让 p2 自己解。

坑三：安装时弹出一长串依赖缺失，逐个确认也装不完。现象是安装向导里一堆红色报错，提示某个 bundle 的版本区间不满足。原因是这个包是按老版本 IDE 的依赖声明打的，新版 IDE 里对应 bundle 的版本已经越界。解决办法只有牺牲法：在一个干净目录里装一份对应年代的老 IDE 专门用来跑这个插件，别在当前主力 IDE 上反复折腾。这对很多人不好接受，但比花两天改依赖声明划算得多。

坑四：插件能打开，但一提交就报错，更新却正常。现象是读操作全通，写操作失败。原因通常不在插件，而在服务端授权或者钩子脚本——读权限一般比写权限宽松，所以表现成“能看不能改”。排查顺序是先确认服务端账号对该路径有写权限，再用命令行客户端在同一个工作副本上试一次提交，命令行能过说明是插件配置问题，命令行也过不去就说明跟插件没关系，别在插件身上浪费时间。

坑五：中文文件名或中文路径下操作报错、乱码。现象是英文文件一切正常，中文名文件更新时报错或者提交后文件名变问号。原因是工作副本编码、IDE 文本编码、系统 locale 三者不一致。解决办法是把三者统一到 UTF-8，启动参数里显式加-Dfile.encoding=UTF-8，并且在提交前检查文件的svn:mime-type属性有没有被错误设置成二进制类型。

5.2 出问题先看这三处，比到处问人快

第一处是configuration目录下那个按日期滚动的日志文件，p2 的解析失败、bundle 启动异常都记在里面。第二处是工作空间里的.metadata/.log，运行时的异常堆栈在这里，插件界面出不来基本都能从这儿找到第一行线索。第三处是手工安装时的cp -v输出和快照 diff，它能直接回答“到底装进去了没有”这个最基础的问题。这三处按顺序看一遍，八成的“玄学问题”都能落地成具体原因。

6. 进阶验证：跑一遍检出到回滚的闭环再决定分发

装完不算完，能跑通一次完整的写操作才算。我的验证流程是固定的四步：先在一个空目录里检出一个小仓库，随便改一个文本文件，提交并写清楚提交说明，最后用 IDE 里的回滚功能把这次提交还原。四步全过，才认为这套插件在这台机器上是可用的。很多人装完只做到“能看到仓库列表”就收工，等到真正提交代码那天才发现写操作是坏的，那时候手上有正在改的代码，处理起来就麻烦了。

回滚那一步尤其重要，它同时验证了两件事：插件能读到刚提交的版本历史，以及它有能力在工作副本上做写操作。如果回滚报错而提交正常，基本可以判定是工作副本状态异常，删掉重检出比修更快。

验证通过之后如果要给全组分发，有一个比逐台安装更省事的做法：把解压出来的 site 目录放到内网共享盘上，保持目录结构不变，然后把这台机器的Install New Software指向这个共享路径。这样后续更新只需要替换共享盘上的目录内容，各台机器重新走一次安装向导就能拿到新版，而且依赖解析还是由 p2 负责，比 dropins 投放更可控。

# 内网共享分发的目录约定：路径里带版本号，方便并行保留两个版本 /mnt/share/eclipse-plugins/svn-1.8.22/ ├── features/ ├── plugins/ ├── content.jar └── artifacts.jar

这个约定的价值在于，将来要回退到旧版时，不需要去找当初的压缩包，共享盘上那份还在，指向旧目录重装即可。目录名不带版本号是这类共享盘上最常见的坏习惯，半年后没人说得清那份东西是哪一版。

我踩过最疼的一次，是在一台没有做快照的机器上手工覆盖安装，装完 IDE 起不来，翻遍日志才定位到是某个 bundle 版本冲突，最后只能重装整个 IDE。从那以后我每次给内网机器装插件，都先打一份 features/plugins 清单存档，再动手，多花的这两分钟远比事后重建环境便宜。希望帮到你。

本文还有配套的精品资源，点击获取