从零构建 Mozc 输入法：macOS 环境下的完整实战指南

从零构建 Mozc 输入法macOS 环境下的完整实战指南【免费下载链接】mozcMozc - a Japanese Input Method Editor designed for multi-platform项目地址: https://gitcode.com/gh_mirrors/mo/mozcMozc 是 Google Japanese Input 的开源版本一套面向多平台macOS、Windows、Linux、Android的日文输入法引擎。这份 Mozc 构建指南会带你走完在 macOS 上从源码拉取、依赖准备、Qt 编译、Bazel 打包到安装验证的全部流程并附上多架构构建与报错自救方法让你不再依赖官方安装包也能随时产出一份属于自己的 Mozc.pkg。为什么值得亲手编译一份 Mozc先说场景。很多人拿到新 Mac 的第一反应是自带日文输入法够用了吧但实际用起来就会发现候选词质量、快捷键习惯、词库同步方式都未必顺手而直接下载官方安装包又没法按自己的偏好做定制。自己动手编译的好处很直接能产出一份带调试符号的版本方便阅读源码、打断点研究输入引擎的工作原理可以按需切换目标 CPU 架构比如在 Apple Silicon 上构建 Intel 版或反过来交叉编译整个构建过程本身就是一次对 Mozc 工程结构的完整体检对想深入阅读 composer、converter、prediction 等核心模块的人尤其有价值。一句话这不是没事找事而是把输入法从黑盒工具变成可读源码的必经之路。本文全部命令都在 macOS 终端中实测可跑照着顺序执行即可。构建之前的环境体检清单动手前先确认你的 Mac 满足下面这张对照表缺哪项补哪项避免做到一半才发现环境不对。项目最低要求说明系统版本64 位 macOS 12 及以上建议 macOS 14新系统对工具链兼容性更好XcodeXcode 16.0 及以上⚠️ 仅安装 Command Line Tools 不够必须完整版Bazelisk任意可用版本它会按src/.bazeliskrc自动选择正确的 Bazel 版本Python3.12 及以上用来跑update_deps.py、build_qt.py等脚本CMake3.18.4 及以上构建 Qt 6 时必需磁盘空间预留 10GB 以上Qt 源码解压加构建产物体积不小其中最容易踩坑的是第一条很多人只跑了xcode-select --install装了精简版工具链结果构建到一半报找不到系统头文件。请直接到 App Store 安装完整 Xcode 并完成首次启动。Bazelisk 和 CMake 可以通过 Homebrew 一键补齐顺手把 Python 也检查一下版本brew install bazelisk cmake python3 --version # 期望输出 3.12 或更高预期结果三条命令都不报错bazelisk --version能打印出版本号。这一步通过后后面基本不会再遇到缺工具类错误。拉取源码两步把仓库和依赖一次补齐克隆仓库并进入 src 目录git clone https://gitcode.com/gh_mirrors/mo/mozc cd mozc/src注意这里必须进入src子目录因为后续所有构建脚本、BUILD 文件都围绕它展开官方文档中的全部命令也是以src为基准目录设计的。用脚本补齐构建依赖python3 build_tools/update_deps.py这一步会自动下载两样关键东西Qt 6.9.1 的源码压缩包约 1GB 级和 Ninja 1.11.0 构建工具并解压到src/third_party目录下。如果你的网络环境对下载源不太友好脚本失败后重跑一次通常就能续上。想使用自己准备的 Qt 二进制时可以给脚本加--noqt参数跳过 Qt 下载。常见坑这一步是纯网络操作耗时取决于带宽别在中途强退终端否则残留的半截压缩包会让后续 Qt 构建直接报压缩包损坏。提前把 Qt 库喂饱Bazel 才有的吃Mozc 的 GUI 组件配置界面、词典工具、渲染窗口依赖 Qt但官方刻意不让你直接用系统 Qt而是用仓库自带的build_tools/build_qt.py从源码裁剪编译一份精简版 Qt。这样做的好处是安装包更小、依赖更可控。python3 build_tools/build_qt.py --release --confirm_license--release表示编译 Release 版 Qt--confirm_license表示你已经确认接受 Qt 的开源许可协议去掉它则会进入交互式确认加--debug可以额外产出调试版 Qt方便后面配合-c dbg构建调试版 Mozc。# 同时产出 Release 与 Debug 两套 Qt python3 build_tools/build_qt.py --release --debug --confirm_license预期结果命令结束且无报错src/third_party/qt目录下出现编译好的 Qt 产物。这一步是全程最耗时的一环Intel 机器上可能超过半小时Apple Silicon 会快不少耐心等待即可。核心环节让 Bazel 打包出 Mozc.pkgQt 就绪后真正的引擎编译就交给 Bazel 了。整个源码被组织成base、composer、converter、dictionary、prediction、session、engine、renderer等模块每个模块都有独立的BUILD.bazel。打包命令会把它们全部编译并封装成一个可安装的 pkg 文件bazelisk build package --config release_build open bazel-bin/mac/Mozc.pkgbazelisk会按src/.bazeliskrc里锁定的版本下载并启动对应 Bazel避免你本地的 Bazel 版本和项目不匹配这类经典问题package是一个别名目标负责把所有可执行文件收拢后打成安装包构建产物落在bazel-bin/mac/Mozc.pkgopen命令会直接弹出 macOS 安装器按提示装到/Library/Input Methods即可。预期结果终端打印INFO: Build completed successfully随后弹出安装窗口。若你只想要构建产物不打算立刻安装跳过open那行即可。三种 CPU 架构的构建玩法从交叉编译到通用二进制默认情况下构建出的二进制架构跟随当前机器——在 arm64 的 Mac 上编译就是 arm64 版。但 Mozc 的--macos_cpus参数允许你显式指定目标架构这一能力在两种场景下尤其有用给旧 Intel Mac 分发、或者打一个两种架构通吃的通用安装包。# 在任意机器上强制产出 x86_64 版 python3 build_tools/build_qt.py --release --debug --confirm_license --macos_cpusx86_64 bazelisk build package --config release_build --macos_cpusx86_64 # 在 Apple Silicon 上构建 Universal Binary python3 build_tools/build_qt.py --release --debug --confirm_license --macos_cpusx86_64,arm64 bazelisk build package --config release_build --macos_cpusx86_64,arm64关键点在于Qt 和引擎两边的架构参数必须保持一致。如果只给 Bazel 指定了--macos_cpus而 Qt 仍按本机架构编译链接阶段会抛出架构不匹配的错误。建议把两组命令连在一起执行形成固定流程。装完别急着用先跑一遍单元测试安装包能用是一回事构建结果是否可靠是另一回事。Mozc 自带庞大的测试套件几乎每个模块都有对应的*_test目标。全量跑一遍能帮你确认当前源码状态是否健康也适合作为后续改动后的回归手段。# 跑全部测试耗时较长建议接上电源 bazelisk test ... --build_tests_only -c dbg # 只跑某个模块的测试比如 base 工具库 bazelisk test base:util_test -c dbg...表示当前目录及子目录下的全部目标--build_tests_only让 Bazel 只编译测试所需目标避免把未用到的二进制也编一遍-c dbg切换为调试构建模式栈信息更完整也和你前面编译的 Debug Qt 配套。测试全部通过后再去系统设置 → 键盘 → 输入法里添加 Mozc切到日文输入试打几句重点观察候选窗口渲染和转换流畅度确认 GUI 组件工作正常。报错自救手册症状、原因、解法速查构建过程不可能一帆风顺下面这张速查表覆盖了 macOS 构建中最高频的几类问题遇到时先对照定位再对症下药。症状原因解法找不到 SDK / 系统头文件报错只装了 Command Line Tools缺完整 Xcode安装完整 Xcode 16 并启动一次Bazel 解析阶段直接失败手动安装的 Bazel 版本与项目不匹配改用 Bazelisk由.bazeliskrc锁定版本Qt 构建中途报压缩包损坏上次update_deps.py下载中断重跑update_deps.py必要时清空third_party/qt_src再构建链接阶段架构不匹配Qt 与引擎的--macos_cpus不一致两组命令使用完全相同的架构参数更新环境后出现诡异编译错误Bazel 增量缓存过期执行bazelisk clean --expunge清空缓存后重建找不到bazel-bin/mac/Mozc.pkg构建未成功或输出路径不对确认日志出现Build completed successfully检查当前目录是src安装后输入法列表里没有 Mozc系统尚未刷新输入法注册重新登录账户再到键盘设置中添加其中Bazel 版本不匹配是最容易忽略的隐性坑官方也反复强调与其手动装一个看起来最新的 Bazel不如老老实实用 Bazelisk。进阶定制改配置、提速度、留本地改动用 config.bzl 定制构建参数src/config.bzl集中了平台相关的可调变量比如想换成系统自带的 Qt 路径可以修改MACOS_QT_PATH。需要注意一个小坑这个文件里~不会被解析为主目录必须写完整绝对路径例如/Users/yourname/myqt。由于config.bzl是被 Git 跟踪的改完记得用下面这招让 Git 忽略你的本地修改避免每次git status都看到它git update-index --assume-unchanged src/config.bzl # 想恢复跟踪时执行 git update-index --no-assume-unchanged src/config.bzl用并发参数缩短构建时间Bazel 默认并发数偏保守如果你的机器核心多可以显式调大并行度。先查一下本机核心数再把--jobs设为对应值sysctl -n hw.ncpu # 查看逻辑核心数 bazelisk build package --config release_build --jobs8更新版本后的标准操作拉取新提交后若遇到怪异的编译报错别急着怀疑代码先执行一次缓存清理再重试这招能解决相当比例的灵异问题bazelisk clean --expunge收尾这份指南适合谁以及还能往哪走这份 Mozc 构建指南的价值在于它把下载源码 → 编译 Qt → Bazel 打包 → 安装自测 → 排错这条链路完整地串了一遍适合三类人——想给旧 Intel Mac 找替代输入法方案的用户、需要定制或二次开发输入引擎的开发者、以及想借真实项目学习 C/Bazel 工程组织的学习者。构建过程中产出的调试版二进制和测试结果也是后续深入源码的绝佳素材。下一步建议通读composer/和converter/目录理解假名组合与转换分词的实现脉络尝试用--macos_cpus打一个 Universal Binary 安装包分发给身边不同架构的 Mac跑一遍bazelisk test ... --build_tests_only -c dbg用测试用例当入口逆向阅读模块设计。最后提醒一句Mozc 的构建流程和依赖版本会随版本迭代调整例如 Qt 版本、Xcode 要求本文描述的是当前源码版本下的行为动手前请以仓库内docs/目录的最新文档为准。【免费下载链接】mozcMozc - a Japanese Input Method Editor designed for multi-platform项目地址: https://gitcode.com/gh_mirrors/mo/mozc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考