• 开发工具

本文以 XVim 仓库的中文说明文档（日文版 README）为核心脉络，完整讲解 Xcode Vim 键位插件 XVim 的安装、分支与发布策略、卸载方式、功能边界、Bug 报告规范以及贡献流程。读完之后，你将能够独立完成 XVim 的构建与安装（包括 Xcode 8 的签名绕过方案）、理解make背后的 UUID 兼容性检查与插件拷贝机制，并掌握按项目规范提交 Bug 报告与测试用例的方法。

一、XVim 是什么：定位与设计目标

XVim 是 Xcode 的 Vim 插件（Xcode plugin for Vim keybindings）。它的设计目标可以概括为一句话：在完全不牺牲 Xcode 任何功能的前提下，提供 Vim 的操作体验。这一点决定了它的实现形态——它不是替换 Xcode 的编辑器，而是以 Xcode 官方插件（.xcplugin）的形式注入到 Xcode 进程中，劫持编辑器的按键事件并转译为 Vim 语义（motion、operator、visual mode、Ex 命令等），同时把 Xcode 特有的能力（Jump To Definition、Run、Breakpoint 等）映射到 Vim 命令（gd、:run、C-]等）。

从仓库结构看，插件以 Xcode 工程 XVim.xcodeproj 组织，核心 Objective-C 源码集中在XVim/目录（如 XVim/XVim.m 主入口、XVim/XVimKeymap.h 键位映射、各类*Evaluator命令解释器），单元测试位于 XVim/Test。

插件的元信息定义在 XVim/Info.plist：CFBundlePackageType为BNDL，并且声明了一组DVTPlugInCompatibilityUUIDs（见 XVim/Info.plist#L21-L46）。每一个 UUID 对应一个 Xcode 版本，Xcode 启动时依据该列表决定是否允许加载插件——这正是后文安装流程中"UUID 兼容性检查"的由来。

二、支持的 Xcode 版本与前置说明

日文版 README 中明确声明支持的版本为：

• Xcode 6
• Xcode 7

需要结合仓库内其他文档补充版本事实：英文 README 进一步说明 Xcode 7 用户应使用 809527b 之前的提交，Xcode 8 用户则需先阅读 INSTALL_Xcode8.md（因为 Xcode 8 起 Apple 不再直接加载第三方插件，需要对 Xcode 重新签名，具体步骤见第五节）。因此本文描述的安装流程适用前提是 Xcode 6 / Xcode 7；若你使用 Xcode 8，请在安装 XVim 之前先完成重签名。

另外，README 公告部分提示：XVim 仓库已迁移至 XVimProject 组织名下。如果你克隆的是旧地址的远程仓库，建议按 Git 仓库迁移的常规做法更新 remote URL（旧 URL 会自动转发到新地址，因此这不是强制操作）。

三、安装：一行make背后的完整机制

日文版 README 给出的安装步骤非常简洁：

下载源码或克隆仓库，然后执行：

$ make

按需创建.xvimrc，重启 Xcode。

这一条命令实际完成了"兼容性检查 → 编译 → 安装到 Xcode 插件目录"三件事，以下结合仓库源码逐层拆解。

3.1make调用的是 xcodebuild Release

Makefile 第 1 行定义了xcodebuild := xcodebuild -configuration，而release/debug目标都依赖uuid目标：

release: uuid $(xcodebuild) Release $(REDIRECT)

其中BUILDLOG变量可选地把构建输出重定向到日志文件（>> $(BUILDLOG)）。也就是说，make等价于执行xcodebuild -configuration Release，最终产物是XVim.xcplugin插件包。

3.2uuid目标：编译前的版本兼容性检查

这是安装流程中最容易被忽略的一步。Makefile#L28-L41 中的uuid目标做了如下事情：

1. 用xcode-select -p取当前 Xcode 的 Developer 路径；

2. 用defaults read从该路径旁的Info文件读出当前 Xcode 的DVTPlugInCompatibilityUUID和CFBundleShortVersionString（版本号）；

3. 在 XVim/Info.plist 中grep这个 UUID；

4. 如果找不到（即 XVim 尚未确认与你当前 Xcode 版本的兼容性），则打印：

   XVim hasn't confirmed the compatibility with your Xcode, Version X.X Do you want to compile XVim with support Xcode Version X.X at your own risk? (y/N)

   此时输入y确认"自担风险继续编译"，Makefile 会用plutil -insert DVTPlugInCompatibilityUUIDs.0 -string <uuid> XVim/Info.plist把当前 Xcode 的 UUID 动态插入 Info.plist 的DVTPlugInCompatibilityUUIDs数组首位；输入其他任意内容则跳过插入，按原有 UUID 列表编译。

这一步解释了为什么不同 Xcode 版本下同一份 XVim 源码可能"装上就加载"，也可能"提示风险后手动加 UUID 才能加载"——是否提示取决于 Info.plist 里是否已经登记了你的 Xcode 版本对应的 UUID。

3.3 插件安装位置：构建阶段的 Copy Files

编译完成后，插件并不是留在构建产物目录里。工程文件 XVim.xcodeproj/project.pbxproj#L111-L122 定义了一个Copy Files构建阶段：

dstPath = "~/Library/Application Support/Developer/Shared/Xcode/Plug-ins"; files = ( XVim.xcplugin in Copy Files );

即构建结束后自动把XVim.xcplugin拷贝到当前用户主目录的~/Library/Application Support/Developer/Shared/Xcode/Plug-ins下。Xcode 启动时扫描该目录发现插件，并弹出"是否加载 XVim"的确认框，选择"允许"后插件生效。

3.4.xvimrc：启动时执行的 Ex 命令文件

安装完成后，日文版 README 建议"按需创建.xvimrc并重启 Xcode"。这个配置文件的读取逻辑在 XVim/XVim.m#L69-L73：

+ (NSString*)xvimrc{ NSString *homeDir = NSHomeDirectoryForUser(NSUserName()); NSString *keymapPath = [homeDir stringByAppendingString: @"/.xvimrc"]; return [[NSString alloc] initWithContentsOfFile:keymapPath encoding:NSUTF8StringEncoding error:NULL]; }

路径固定为~/.xvimrc。启动时的解析在 XVim/XVim.m#L263-L269 的parseRcFile中实现——逐行读取文件，给每行加上:前缀后作为 Ex 命令执行：

- (void)parseRcFile { NSString* rc = [XVim xvimrc]; for (NSString *string in [rc componentsSeparatedByString:@"\n"]) { [self.excmd executeCommand:[@":" stringByAppendingString:string] inWindow:nil]; } }

所以.xvimrc的每一行都是一条 Ex 命令，例如官方功能列表（Documents/Users/FeatureList.md）给出的示例：

set ignorecase set wrapscan set guioptions=r nmap n e

此外还有两个实用细节：

• 调试日志：在.xvimrc中写入set debug（需要重启 Xcode 生效）会开启调试模式，XVim/XVim.m#L251-L261 中通过观察debug选项的 KVO 变化，把日志写入~/.xvimlog；同时 Xcode 菜单会出现 "Run Test" 入口（见 XVim/Test/XVimTester.m 的说明）。这对后文的 Bug 报告环节非常关键。
• 选项即参数：.xvimrc中set的选项（如timeoutlen默认 1000ms 的多键映射超时、laststatus默认 2、[no]expandtab、[no]vimregex等）详见功能列表文档的 Options 一节，可直接用于按个人习惯定制行为。

四、分支与发布策略

日文版 README 对分支体系有明确定义，这也是后续理解 Bug 处理流程和贡献流程的前提：

• 发布版本（tag / Release）：发布版本是 master 分支上的 tag。这些 tag 上的代码和文档都经过了整理，状态稳定。普通用户应使用某个发布版本。
• master 分支：最稳定的分支。致命 Bug 的修复、以及 'develop' 分支上开发完成的功能会被合并进 'master'。如果你发现某个发布版本有致命 Bug，可以尝试最新的 'master'。
• develop 分支：新功能和非致命 Bug 修复合并进此分支。想体验实验性功能时使用此分支。
• 其他分支：都是面向 'develop' 的临时功能开发或 Bug 修分支，最终都会合并回 'develop'。Pull Request 一律指向 'develop' 分支。

可以推断出项目的合并方向是：功能分支 →develop→master（打 tag 发布），develop承担了"缓冲分支"的角色（Documents/Developers/PullRequest.md 中称之为 'Master' 的 buffer）。

五、Xcode 8 用户的前置操作：重签名 Xcode

虽然日文版 README 的主安装流程面向 Xcode 6/7，但仓库同时提供了 INSTALL_Xcode8.md。由于 Xcode 8 起 Apple 决定不再加载第三方插件，必须先对 Xcode 重新签名，概要步骤如下（引自该文档）：

1. 关闭 Xcode；
2. 准备代码签名证书：若已有 Apple 开发者项目的证书可直接使用；否则打开"钥匙串访问"（Applications → Utilities），选中左侧login钥匙串，通过 "Certificate Assistant → Create a Certificate" 新建：

输入证书名称（文档建议使用易于区分的名称，例如XcodeSigner，因为它后面要用于命令行），类型选择 "Code Signing"：

3. 在终端重新签名 Xcode（耗时较长）：

$ sudo codesign -f -s XcodeSigner /Applications/Xcode.app # Xcode 路径不同请自行替换

4. 回到 XVim 目录，按上文第三节的正常流程make构建。

六、卸载

日文版 README 给出两种方式。

方式一：命令卸载

$ make uninstall

对应 Makefile#L25-L26：

uninstall: rm -rf "$(HOME)/Library/Application Support/Developer/Shared/Xcode/Plug-ins/XVim.xcplugin"

方式二：手动卸载

直接删除以下目录：

$HOME/Library/Application\ Support/Developer/Shared/Xcode/Plug-ins/XVim.xcplugin

两个路径与 3.3 节构建阶段的 Copy Files 目标路径完全一致——卸载本质上就是把构建阶段拷贝进去的XVim.xcplugin移除。删除后重启 Xcode，加载弹窗与 Vim 键位即消失。

七、功能一览：XVim 覆盖了哪些 Vim 能力

日文版 README 将功能细节指向独立的功能列表文档 Documents/Users/FeatureList.md。该文档维护了 XVim 当前支持的命令全集，核心覆盖面包括：

光标移动（Motion）：b B f F gg G h j k l w W t T 0 $ ^ % + - { } ( ) n N 'M H L，支持,与;重复上次f/t搜索，支持v` 切换选择区首尾包含/排除。

标记（Mark）：文件内与全局标记均支持，^（最后插入点）与.（最后修改点）标记可用，gi（回到最后插入点进入插入模式）可用。文档也如实记录了已知问题：删除标记所在行之前的行时，标记不会随行上移，仍停留在绝对位置。

滚动与跳转（Scroll / Jump）：C-d C-f C-e C-u C-b C-y zz zb zt；C-o C-i gd。其中C-i在 Xcode 默认键位中是 "Editor-Structure-Re Indent"，如需用作跳转需先在 Xcode 偏好设置的 Key Bindings 中清掉^I；gd对应"打开光标下的文件/跳转定义"。

插入、删除、复制（Insert / Yank / Change）：a A i I o O（插入模式下Ctrl-o临时进入普通模式）；d dd D y yy Y c cc C r s S x X。

可视模式与文本对象：v V Ctrl-v（块选择插入亦支持）；文本对象ib iB i( i) i{ i} i[ i] i> i< i" i' iw iW及对应a系列。

搜索替换：/ ? # \* g* g# :s n N，正则默认使用 ICU regex 格式，也可用[no]vimregex选项切换为 Vim 风格正则（当前支持\< \>词边界、\c \C大小写控制）。

Ex 命令（节选，完整表格见 Documents/Users/FeatureList.md#L161-L209）：

Ex 范围语法支持:X,Y、:X-N,Y、:X+N,Y、:X、:X-N、:X+N、:-N、:+N等形式，其中X、Y可以是数字、标记引用（如'a）、.或$。范围命令支持y[ank] d[elete] copy t m[ove] sort s[ubstitute] !，示例如:1,.y、:4,5m$、:'a,'bd、:5t10。

窗口操作（与 Vim 的差异点）：Xcode 没有"同一窗口内多个等价文本视图"的概念，而是"主编辑器 + 若干 assistant editor"的结构，主编辑器不能被 split，只能增删 assistant editor。因此 XVim 的窗口操作在行为上略有不同：

以上命令均有C-w C-x形式的别名（如C-w C-c等同C-w c）。

其他能力：折叠zc zm zM zo zO zr zR（zC/zO/zr因 Xcode 无对应行为而映射到zc/zM/zo）；宏录制q @；.重复命令；导航C-]（Jump To Definition）、C-t（Go Back）；XVim 原创 Ex 命令:run（Xcode 运行）、:make（Xcode 构建）、:xhelp、:xcmenucmd、:nissue/:pissue、:njump/:pjump等。

键位映射：支持map nmap vmap imap omap五种 map 命令，多键映射的默认超时 1 秒（1000ms），可用timeoutlen选项调整。示例：

nmap n e imap ' <Esc> nmap u 5jiInsert some text<Esc> nmap ,w :w<cr>

八、Bug 报告：一份合格的报告需要哪些信息

日文版 README 坦承：XVim 有时会令 Xcode 崩溃，虽然团队在持续消除 Bug 但难度很大。当你遇到崩溃或异常时，报告需包含以下信息：

• 崩溃信息（崩溃时 Xcode 会显示线程堆栈栈 trace，请复制下来）；
• 触发崩溃的操作序列（一连串的按键或鼠标点击）；
• 当时正在编辑的文本；
• Xcode 版本；
• XVim 版本（你构建的版本号或提交号）。

若仅凭上述信息仍难以定位，维护者可能会请你按官方教程抓取调试日志——对应 3.4 节提到的set debug+~/.xvimlog日志机制。

进一步建议：为 Bug 写测试用例。日文版 README 指出，写测试用例不需要修改任何源码，只需按 Documents/Developers/PullRequest.md 中 "Write test" 一节所述的 7 个项目把内容写进 Issue 即可。这 7 个项目对应测试用例的七个要素：

1. 初始文本
2. 初始插入点（索引从 0 开始）
3. 初始选区（无选区则为 0）
4. 要执行的命令
5. 期望的结果文本
6. 期望的结果插入点（索引从 0 开始）
7. 期望的结果选区（无选区则为 0）

在源码层面，这 7 个参数正是 XVim/Test/XVimTestCase.h#L11-L18 中XVimMakeTestCase宏的实参。PullRequest.md 给出的例子可以直接作为 Issue 模板参考：

XVimMakeTestCase(@"abc", 0, 0, @"l", @"abc", 1, 0)

含义：在文本"abc"、插入点索引 0（位于 'a'）、无选区的状态下执行l，结果应为文本不变、插入点移到索引 1（'b'）、无选区。另一个多行例子：

XVimMakeTestCase(@"abc\nabc", 4, 0, @"iabc<CR><ESC>dd", @"abc\nabc", 4, 0)

即在两行abc文本上，从第二行 'a' 开始执行插入加删除行操作，验证最终文本与光标位置。正式提交 PR 时，这些用例会被追加到 XVim/Test 下对应类别（如XVimTester+Motion.m、XVimTester+Operator.m）的XVimMakeTestCase数组中。

九、Bug Issue 的处理流程

日文版 README 明确规定了 Bug 类 Issue 的七步处理顺序：

1. 确认 Bug 可复现，打上Bug标签；
2. 在develop分支修复该 Bug；
3. 由报告者确认 Bug 已被修复；
4. Issue 打上Done标签；
5. 确认该修复没有引入其他副作用；
6. 合并进master分支；
7. 关闭 Issue。

该流程仅适用于Bug类 Issue。这一流程与第四节的分支模型互为印证：修复必须先进develop，经确认与回归验证后才允许进master。

十、贡献流程：提交 Pull Request 之前

日文版 README 欢迎一切建议、Bug 报告与功能请求，并明确：提交 Pull Request 之前请先阅读Documents/Developers/PullRequest.md。该文档规定的完整流程如下：

1. Fork XVim 仓库；
2. 检出develop分支（不要直接在 master 上工作）；
3. 创建功能分支（推荐，避免多个修改混在同一个待合并分支里导致挑选 commit 困难）；
4. 实现功能 / 修复 Bug（方法与调试方式参考 Documents/Developers/DevGuide.md）；
5. 运行 / 编写测试，确认全部测试通过（XVim 自带单元测试用于防止回归；注意运行 "Run Test" 会删除并可能保存当前文本内容，应在 dummy 项目上执行，结果出现在新建窗口中，未通过的用例需查看 "Description" / "Message" 列定位）；
6. 如需，更新 Documents/Users/FeatureList.md——纯 Bug 修复通常不需要，但新增或改变功能行为时必须同步更新；
7. 向develop分支发起 Pull Request，发起前自查四项：工作在develop或其分支上、已为修改编写测试用例、全部测试通过、按需更新了 FeatureList.md。

十一、项目的其他说明

• Bountysource：XVim 曾接入 Bountysource 平台。如果你希望某个 Issue 被尽快解决，可以为其悬赏（贡献者会优先处理悬赏 Issue，但不作保证）；也可以支持整个项目团队。若目标 Bug 或功能尚未成为 Issue，需先创建 Issue。
• 捐赠去向：由于项目作者声明不以盈利为目的，日文版 README 说明捐赠资金直接捐给 2011 年东日本大地震及海啸的受灾者（通过 PayPal 的慈善捐赠页面直捐以减少转账手续费），也可选择通过 Bountysource 支持项目本身，两者不互斥。
• 许可证：XVim 采用 MIT License，许可证全文见仓库根目录 LICENSE。

十二、小结

围绕日文版 README 这条主线，XVim 的使用路径可以浓缩为：

1. 安装：克隆仓库 →make（内部先做DVTPlugInCompatibilityUUID兼容性检查，再xcodebuild Release并自动把XVim.xcplugin拷入~/Library/Application Support/Developer/Shared/Xcode/Plug-ins）→ 按需写~/.xvimrc（逐行作为 Ex 命令执行）→ 重启 Xcode 并允许加载；Xcode 8 用户需先按 INSTALL_Xcode8.md 重签名 Xcode。
2. 选版本：普通用户用 tag 发布版；遇到发布版致命 Bug 试最新 master；想尝鲜用 develop；所有 PR 指向 develop。
3. 卸载：make uninstall或手动删除上述插件目录。
4. 反馈：Bug 报告附崩溃栈、操作序列、文本、Xcode 版本与 XVim 版本；能附 7 要素测试用例更佳；Bug 类 Issue 按"复现确认 → develop 修复 → 报告者验证 → Done 标签 → 副作用检查 → 合并 master → 关闭"七步流转。

这套"插件包 + UUID 白名单 + Ex 命令化配置 + 测试用例驱动"的组合，使 XVim 在不改动 Xcode 的前提下，把 Vim 的按键语义完整嫁接进了 Xcode 编辑器。

• 开发工具