简介：这份资源面向需要在Android平台上挂载NTFS格式存储设备的开发者与系统移植人员，提供ntfs-3g的完整移植源码，解决TF卡、U盘及SATA硬盘在Android系统中无法识别NTFS分区的问题。压缩包共300个文件，约1.39MB，以73个C源文件与61个头文件为核心实现，辅以42个plo、34个po本地化资源、28个in模板及多份Makefile、am构建脚本，并包含configure、libtool等Autotools配套文件，整体结构贴近原生ntfs-3g工程，便于直接mm编译。解压至external目录后即可编译，成功后可通过命令行手动挂载，也可将Ntfs.cpp、Ntfs.h加入system/vold实现开机自动挂载。目前已有1835人学习下载，适合具备一定Android系统与Linux内核基础、希望快速完成NTFS读写支持的开发者参考，能省去从零移植与调试构建脚本的时间。
1. 拿到一份能直接 mm 编译的 ntfs-3g 移植源码，到底省了多少事
做过 Android 外接存储的人大概都经历过这个场景：设备上插了一块 NTFS 格式的移动硬盘，系统自带的 vold 和 FUSE 层根本不认，/mnt/media_rw下挂载失败，日志里只有一句含糊的mount failed。想支持 NTFS，绕不开 ntfs-3g 这套用户态驱动，但把 Linux 上的源码搬到 Android 编译系统里，光 Android.mk 和依赖库就能折腾掉一整天。这份资源给的就是一个已经移植好、放进源码树就能mm编译的 ntfs-3g 工程，目标读者是需要在 Android 设备上读写 NTFS 分区的系统开发者和做外设兼容的工程师。它把交叉编译、libfuse 适配、Android 构建脚本这些脏活提前干完了，你拿到手的第一件事不是改代码，而是先把它编出来看看能不能跑通。
2. 工程结构与构建链路：从源码树到可执行文件
2.1 目录布局与模块划分
这份移植源码的目录结构基本沿用了 ntfs-3g 上游的布局，但外层套了一层 Android 构建需要的壳。常见做法是把整个工程放在external/ntfs-3g/下，和 AOSP 里其他 external 库平级，这样mm命令才能识别到它。核心目录大致是这样：
external/ntfs-3g/ ├── Android.mk # 顶层构建脚本，mm 的入口 ├── libntfs-3g/ # NTFS 读写核心库，产出 libntfs-3g ├── libfuse/ # FUSE 用户态库适配层 ├── ntfs-3g/ # 主程序，产出 ntfs-3g 可执行文件 ├── ntfsprogs/ # 配套工具集（mkntfs、ntfsfix 等） ├── include/ # 公共头文件 └── config.h # 交叉编译时生成的配置头libntfs-3g是整个工程的地基，负责解析 NTFS 的 MFT、属性列表、数据运行（runlist）这些底层结构；libfuse是 Android 上跑用户态文件系统的关键，ntfs-3g 通过它把文件操作转发到内核 FUSE 模块；ntfs-3g主程序则是把两者粘起来，实现mount语义。ntfsprogs里的工具不是必须的，但调试阶段很有用，比如分区挂了可以用ntfsfix清一下日志。
2.2 Android.mk 的关键写法
mm能编起来，全靠 Android.mk 写对了。这份源码里最值得看的是它怎么处理静态库和可执行文件的依赖关系。下面是一段典型的构建脚本片段：
# 编译 libntfs-3g 静态库 include $(CLEAR_VARS) LOCAL_MODULE := libntfs-3g LOCAL_SRC_FILES := $(wildcard libntfs-3g/*.c) LOCAL_C_INCLUDES := $(LOCAL_PATH)/include $(LOCAL_PATH)/libntfs-3g LOCAL_CFLAGS := -DHAVE_CONFIG_H -D_FILE_OFFSET_BITS=64 LOCAL_STATIC_LIBRARIES := libfuse include $(BUILD_STATIC_LIBRARY) # 编译 ntfs-3g 可执行文件 include $(CLEAR_VARS) LOCAL_MODULE := ntfs-3g LOCAL_SRC_FILES := $(wildcard ntfs-3g/*.c) LOCAL_C_INCLUDES := $(LOCAL_PATH)/include LOCAL_CFLAGS := -DHAVE_CONFIG_H LOCAL_STATIC_LIBRARIES := libntfs-3g libfuse LOCAL_LDLIBS := -llog include $(BUILD_EXECUTABLE)这里有几个参数值得说明。LOCAL_CFLAGS里的-D_FILE_OFFSET_BITS=64是必须的，NTFS 分区动辄上 T，不开大文件偏移会在读写超过 2GB 的文件时直接翻车。LOCAL_STATIC_LIBRARIES把 libfuse 和 libntfs-3g 静态链进去，避免 Android 上动态库搜索路径的玄学问题。LOCAL_LDLIBS := -llog是为了让代码里能用__android_log_print打日志，调试挂载失败时全靠它。
2.3 交叉编译工具链与 config.h
上游 ntfs-3g 用 autotools 生成 config.h，Android 构建系统里没有 configure 这一步，所以这份源码直接带了一个预生成的 config.h。常见做法是根据目标架构（arm、arm64、x86_64）分别准备 config.h，或者用宏在编译期判断。里面几个关键宏：
| 宏名 | 作用 | 建议值 |
|---|---|---|
HAVE_CONFIG_H | 启用 config.h | 必须定义 |
ENABLE_NTFS_PROGS | 是否编译工具集 | 调试时开 |
FUSE_USE_VERSION | FUSE API 版本 | 26 或 30，看内核 |
HAVE_SETXATTR | 扩展属性支持 | Android 上一般关 |
FUSE_USE_VERSION这个宏特别容易踩坑，写高了编译报错，写低了运行时 ioctl 对不上。Android 不同版本内核带的 FUSE 版本不一样，我一般先在目标设备上cat /proc/filesystems | grep fuse确认，再回来改这个宏。
2.4 编译产物与验证
在源码树根目录执行：
source build/envsetup.sh lunch <你的目标产品> mm -j8 external/ntfs-3g编完之后产物在out/target/product/<device>/system/bin/ntfs-3g，配套的mkntfs、ntfsfix也在同目录。验证分两步：先adb push到设备/system/bin/，再手动挂载测试。
adb push out/target/product/<device>/system/bin/ntfs-3g /system/bin/ adb shell chmod 755 /system/bin/ntfs-3g adb shell mkdir -p /mnt/ntfs adb shell ntfs-3g /dev/block/sda1 /mnt/ntfs如果挂载成功，/mnt/ntfs下就能看到分区里的文件。失败的话先看dmesg | grep fuse，再看 ntfs-3g 自己的日志输出，大部分问题出在权限和 FUSE 设备节点上。
3. 核心模块拆解：挂载流程与读写链路
3.1 ntfs-3g 主程序的挂载入口
ntfs-3g 主程序的main函数干的事比想象中多：解析命令行参数、打开块设备、初始化 NTFS 卷、建立 FUSE 会话、进入事件循环。核心逻辑集中在ntfs-3g.c里，下面这段是挂载流程的骨架：
int main(int argc, char *argv[]) { ntfs_volume *vol; struct fuse_args args = FUSE_ARGS_INIT(argc, argv); // 1. 解析挂载选项，比如 -o rw,uid=1000 if (ntfs_parse_options(&args, &opts) != 0) return 1; // 2. 打开块设备，O_RDWR 表示可读写 int fd = open(opts.device, O_RDWR); if (fd < 0) { ntfs_log_error("无法打开设备 %s\n", opts.device); return 1; } // 3. 挂载 NTFS 卷，读取引导扇区、MFT 位置 vol = ntfs_mount(opts.device, opts.mount_flags); if (!vol) { ntfs_log_error("NTFS 卷挂载失败\n"); close(fd); return 1; } // 4. 进入 FUSE 主循环，把操作回调注册进去 return fuse_main(args.argc, args.argv, &ntfs_fuse_ops, vol); }ntfs_mount是 libntfs-3g 提供的接口，它会读分区第一个扇区的 NTFS 引导记录，定位 MFT 的起始簇，然后加载根目录。这一步失败通常意味着分区表不对或者分区被 BitLocker 之类的东西加密了。fuse_main是 libfuse 的入口，它把ntfs_fuse_ops里定义的一堆回调（getattr、read、write、readdir）注册到内核，之后所有文件操作都由内核转发过来。
3.2 FUSE 操作回调的实现
ntfs_fuse_ops是一个struct fuse_operations，里面每个函数指针对应一个文件系统操作。以read为例：
static int ntfs_fuse_read(const char *path, char *buf, size_t size, off_t offset, struct fuse_file_info *fi) { ntfs_inode *ni = (ntfs_inode *)fi->fh; ntfs_attr *na; s64 ret; // 找到文件的数据属性 na = ntfs_attr_open(ni, AT_DATA, AT_UNNAMED, 0); if (!na) { ntfs_log_error("打开数据属性失败: %s\n", path); return -EIO; } // 从指定偏移读取，ntfs_attr_pread 内部处理 runlist ret = ntfs_attr_pread(na, offset, size, buf); ntfs_attr_close(na); return ret < 0 ? -EIO : ret; }fi->fh是打开文件时存的私有数据，这里直接放了ntfs_inode指针，省去每次按路径查找的开销。ntfs_attr_pread是 libntfs-3g 的核心读函数，它根据 NTFS 的 runlist 把逻辑偏移映射到物理簇，再通过pread从块设备读数据。NTFS 的碎片化程度直接影响这个函数的性能，碎片多的分区读大文件会明显变慢。
3.3 libntfs-3g 的 MFT 解析
NTFS 的一切都围绕 MFT（主文件表）展开，每个文件在 MFT 里有一条记录，记录里包含标准信息、文件名、数据属性等。ntfs_inode结构体就是 MFT 记录在内存里的映射。打开一个文件时，libntfs-3g 会：
- 从路径逐级解析目录项，拿到目标文件的 MFT 记录号
- 读 MFT 记录，解析属性列表
- 对常驻属性（resident）直接返回内存指针，对非常驻属性（non-resident）解析 runlist
ntfs_inode *ntfs_inode_open(ntfs_volume *vol, MFT_REF mref) { ntfs_inode *ni = ntfs_calloc(sizeof(ntfs_inode)); ni->mft_no = MREF(mref); // 读 MFT 记录到 ni->mrec if (ntfs_mft_record_read(vol, ni->mft_no, ni->mrec) != 0) { free(ni); return NULL; } // 解析属性，填充 ni->attr_list if (ntfs_attr_list_init(ni) != 0) { ntfs_inode_close(ni); return NULL; } return ni; }MFT_REF是 MFT 记录号的编码，低 48 位是记录号，高 16 位是序列号，用来检测记录是否被复用。这个设计在文件被删除又新建时特别重要，序列号不匹配就说明拿到的是过期记录，必须重新查找。
3.4 写路径与日志恢复
写操作比读复杂得多，因为 NTFS 是日志文件系统。ntfs-3g 在写之前会先写$LogFile，确保崩溃后能恢复。ntfs_attr_pwrite内部会调用ntfs_logfile_*系列函数记录事务。如果设备在写入过程中断电，下次挂载时 ntfs-3g 会检测到日志未提交，自动回放日志。这也是为什么强制拔盘后分区有时会变成只读——日志回放失败，ntfs-3g 为了保护数据会拒绝写入。
注意：调试写路径时不要直接拔盘，用
umount正常卸载，否则分区很容易进入 dirty 状态，得靠ntfsfix才能救回来。
4. 避坑与常见问题排查
4.1 挂载报错 "fuse: device not found"
现象是执行 ntfs-3g 后立刻返回，日志里写着fuse: device not found, try 'modprobe fuse' first。原因是 Android 内核没有编译 FUSE 模块，或者/dev/fuse设备节点不存在。先在设备上ls -l /dev/fuse确认，没有的话说明内核配置里CONFIG_FUSE_FS没开，得重新编内核。有节点但还是报错，检查 SELinux 策略，ntfs-3g进程需要fuse_device的访问权限，常见做法是加一条allow untrusted_app fuse_device:chr_file rw_file_perms;。
4.2 编译报错 "undefined reference tofuse_main"
链接阶段找不到 libfuse 的符号，原因是LOCAL_STATIC_LIBRARIES里没加 libfuse，或者 libfuse 的 Android.mk 没被正确 include。检查顶层 Android.mk 有没有include $(call all-makefiles-under,$(LOCAL_PATH))，这行会把子目录的构建脚本都拉进来。另一个可能是 libfuse 编成了动态库，而 ntfs-3g 按静态链接找，统一改成BUILD_STATIC_LIBRARY就行。
4.3 挂载成功但读写全是 I/O error
分区能挂上，ls也能列目录，但一cat文件就报Input/output error。这种多半是_FILE_OFFSET_BITS=64没定义，导致 32 位偏移在超过 2GB 的位置溢出。检查 Android.mk 里LOCAL_CFLAGS有没有这个宏，arm 32 位架构上尤其容易漏。还有一种情况是块设备本身有坏道，dmesg里会有I/O error, dev sda的字样，那就不是软件问题了。
4.4 中文文件名显示乱码
NTFS 用 UTF-16 存文件名，ntfs-3g 默认按 locale 转码。Android 上 locale 经常是C，转出来就是乱码。解决办法是在挂载选项里加-o iocharset=utf8，强制按 UTF-8 输出。如果还乱，检查config.h里HAVE_ICONV有没有开，没开的话 ntfs-3g 用的是内置的简化转码表，对某些字符支持不全。
4.5 mm 编译通过但 push 后无法执行
mm编出来的二进制 push 到设备上执行报Permission denied或者No such file or directory。前者是权限问题，chmod 755解决；后者通常是动态链接器路径不对，用readelf -l ntfs-3g | grep interpreter看一下，Android 上应该是/system/bin/linker64或/system/bin/linker。如果指向了主机的/lib/ld-linux.so，说明编译时用了主机工具链而不是交叉工具链，检查lunch选的目标对不对。
5. 二次开发与改造：从能跑到好用
5.1 裁剪不需要的模块
上游 ntfs-3g 带了一堆工具和特性，实际产品里未必都用得上。比如ntfsprogs里的mkntfs、ntfsresize在只读场景下完全没必要编，去掉能省不少空间。做法是在顶层 Android.mk 里把ntfsprogs的 include 注释掉，只保留libntfs-3g、libfuse和ntfs-3g三个模块。裁剪后编出来的二进制大概能小 30% 左右，对 system 分区紧张的设备很实用。
5.2 增加自动挂载支持
手动敲ntfs-3g /dev/block/sda1 /mnt/ntfs只能用于调试，产品里得让系统自动挂。常见做法是改vold的fs_mgr，在检测到 NTFS 分区时调用 ntfs-3g。具体是在system/vold/下加一个ntfs的FsType分支，挂载时 fork 一个 ntfs-3g 进程。这里要注意 SELinux 上下文，/mnt/ntfs目录得打上media_rw之类的标签，否则应用层访问不了。
5.3 性能调优的几个参数
ntfs-3g 默认的读写块大小是 4096 字节，对机械硬盘够用，对 SSD 或者高速 U 盘偏小。可以在挂载选项里加-o big_writes让 FUSE 支持大块写，减少内核和用户态的上下文切换。另外-o max_read=131072能把单次读的上限提到 128KB，顺序读大文件时提升明显。这两个选项在ntfs-3g.c的选项解析里都有对应处理，改起来不难。
// 在 ntfs_parse_options 里加自定义选项 { "big_writes", 0, &opts.big_writes, 1 }, { "max_read", 1, NULL, 'r' },5.4 一个验证改造是否生效的小技巧
改完代码别急着全量刷机，用adb push单独替换/system/bin/ntfs-3g就能验证。挂载后跑一个简单的读写测试：
adb shell "dd if=/dev/zero of=/mnt/ntfs/test.bin bs=1M count=100" adb shell "dd if=/mnt/ntfs/test.bin of=/dev/null bs=1M"看两次的耗时，对比改造前的数据。如果写速度没变化，先确认big_writes选项真的传进去了，可以在ntfs-3g.c里加一行ntfs_log_info("big_writes=%d\n", opts.big_writes);打出来看。
5.5 我踩过的一个坑
有次改完挂载选项，测试机上一切正常，换到另一台设备上直接挂不上。查了半天发现是那台设备的内核 FUSE 版本低，不支持big_writes，ntfs-3g 遇到不认识的选项直接报错退出。从那以后我每次加新挂载选项，都强制在ntfs_parse_options里加一个降级逻辑：选项不被支持时打警告但继续挂载，而不是直接失败。这个习惯帮我省了不少现场排查的时间。希望帮到你。
本文还有配套的精品资源，点击获取
