Rust 的模块系统与文件系统绑定紧密，但初学时常遇到编译错误，比如 'module is private' 或 'unresolved import'。这类问题通常不是语法错，而是文件结构和可见性设置没对上。下面分几个常见场景给出处理路径和验证方法。

先搞清楚模块与文件的映射关系

Rust 的模块树直接映射到文件系统。模块名 foo 对应 foo.rs 或 foo/mod.rs。如果嵌套模块如 crate::bar::baz，文件结构可能是 bar/baz.rs 或 bar/baz/mod.rs。关键判断：若模块下有多个子模块或需要共享私密项，用文件夹加 mod.rs；若只有一个单文件模块用同名 .rs 文件。风险：不要在同一目录下同时存在 foo.rs 和 foo/ 文件夹，Rust 会报冲突错误。

这段映射规则是调试 import 错误的第一步。如果出现 'file not found for module'，先检查文件名拼写和路径层级：lib.rs 或 main.rs 中声明的 mod foo; 会告诉编译器去找 foo.rs 或 foo/mod.rs。如果两者都不存在，编译器会直接报错。操作动作：在项目根目录执行 tree src/ 查看文件结构，确认每个声明都有对应文件。

模块声明：放在 lib.rs 还是单独文件？

在 Rust 中，模块声明通常放在 lib.rs 或 main.rs 中。如果你在 lib.rs 中写 mod foo;，Rust 会默认在同一目录下查找 foo.rs 或 foo/mod.rs。优先使用 foo.rs 方式，因为 foo/mod.rs 在 Rust 2018 后已不再推荐，可能导致编译警告。若你发现模块内文件较多，再考虑转为文件夹加 mod.rs 的结构。

这里的常见误区：在新项目中继续沿用旧版 mod.rs 写法（如 mod foo/mod.rs）。虽然 2018 版仍兼容，但如果你同时存在 foo.rs 和 foo/ 文件夹，编译器可能优先解析为模块文件而非文件夹，导致找不到子模块。解决办法：统一选择一种风格。新项目直接使用 lib.rs + 子目录模块文件（如 foo.rs），避免 mod.rs 的歧义。迁移旧项目时，可用 cargo fix --edition-idioms 自动调整，但需要手动检查是否有冗余文件。

子模块访问权限：pub 只加在 mod 上不够

子模块默认对外是私有的。要使子模块对父级或外部可见，需在 mod 前加 pub，例如 pub mod sub。若父模块需要访问子模块内的公开项，子模块的 pub 还不够——还需要将项本身声明为 pub。常见错误是只加了模块 pub 但函数依然是私有的，导致编译报错。检查方法：编译时看是否有 'module is private' 错误。

验证步骤：假如你有 src/lib.rs 声明了 pub mod helpers;，而 helpers.rs 里定义了 fn do_thing()（无 pub），那么从 lib.rs 里调用 helpers::do_thing() 时会报错。正确做法是将函数也标记为 pub fn。如果是多层嵌套，父模块想要访问子模块中的公开项，还需要在路径中逐级加 pub。例如 mod outer { pub mod inner { pub fn foo() {} } }，外层可以通过 outer::inner::foo 访问。

路径引用：用 crate、super 还是 self？

当使用 crate 关键字引用同 crate 内的模块时，例如 crate::module::function，路径始终以 crate 开头。在 lib.rs 中声明的模块默认在根作用域，无需前缀。常见坑：在子模块中引用同级子模块时，不要用 self:: 过度，而要用 super:: 回到父级再向下访问。检查方法：如果 'unresolved import' 错误，检查路径是否使用了正确的相对或绝对方式。

具体例子：在 src/network/server.rs 中想引用 src/network/client.rs 中的 connect()。错误写法 use self::client::connect; 会认为 client 是 server 的子模块。正确写法：use super::client::connect;（从父模块 network 向下找）。如果模块层级深，推荐用绝对路径 use crate::network::client::connect; 更清晰。

什么时候该拆分模块？避免过早优化

不要在一开始就过度拆分模块。建议当一个文件超过 300～500 行时，或者有多个功能独立的代码块时，再拆分。判断依据：如果函数组之间有明显的职责边界，且可能被多文件共享，可以拆分为子模块。风险：过早拆分会导致难以理解的间接引用，反而增加维护成本。操作动作：先自然生长在单文件中，觉得混乱时使用 IDE 的提取模块功能（如 Rust Analyzer）快速生成 mod.rs。

边界条件：如果是库项目，公有 API 的拆分要谨慎，因为子模块的路径会暴露给外部使用。拆分后记得在 lib.rs 或根模块中重新导出 pub use，保持接口稳定。验证方法：编译通过且外部调用路径未变即成功。

避坑：mod.rs 的混用问题

一些旧项目使用 mod.rs，但在 Rust 2018 之后，如果路径中包含同名的 .rs 文件和文件夹，编译器可能优先解析为模块文件而非文件夹。解决办法：统一使用文件夹加 mod.rs 或单文件，不要混用。迁移时，可用 cargo fix 自动调整，但需手动检查是否有多余的文件。操作建议：新项目直接使用 lib.rs + 子目录模块文件（如 foo.rs），避免 mod.rs 的歧义。

验证步骤：执行 cargo check --all-features 时如果出现 'file for module `foo` found at both foo.rs and foo/mod.rs' 的错误，说明有冲突。删除其中一个文件后重新编译。如果使用 cargo fix 迁移，建议先备份项目，因为自动重命名可能改变模块引用路径。

最后，如果仍然遇到奇怪的编译错误，可以检查 Cargo.toml 中 edition 设置是否为 2018 或 2021，某些旧版行为差异会导致解析歧义。保持文件系统整洁、声明与文件名一致，多数问题可以避免。