Rust Cargo workspace 中子模块导入 Config 时为何出现 unresolved import？

2026-11-04数据阿明

结论：先确认这份文件属于哪个 crate

如果 cmd_config.rs 通过 tool/src/lib.rs 中的 pub mod command; 加载，且 config 也在这个 lib.rs 中声明，应使用：

use crate::config::Config;

Cargo workspace 不会改变这条规则。crate 指向当前正在编译的 crate 的根，workspace 本身不会成为模块路径的一部分。

按问题给出的模块声明，这条导入应当成立。不过，由于没有提供 main.rs、完整的 Cargo.toml 和完整错误位置，还不能确定实际失败的是哪个编译目标。编译器交替建议 tool::config 和 crate::config 时，应优先检查同一份源码是否同时被 library 和 binary 加载。

为什么同一份代码会收到不同建议？

先区分三个层次：

workspace 组织多个 package，协调构建和依赖解析。
package 由一个 Cargo.toml 定义，可以包含 library、binary 等目标。
crate 是一次独立编译的单元，有自己的模块树和根模块。

在默认目录布局下，src/lib.rs 是 library crate 的根，src/main.rs 是 binary crate 的根。即使它们属于同一个 package，也各自拥有独立的 crate::。

问题中的第一条提示：

unresolved import
help: a similar path exists: 'tool::config'

这与下面的情况相符：当前代码在 binary crate 中编译，binary 根下没有 config 模块，但可以通过名为 tool 的 library crate 访问它。

如果同一份文件作为 library 的模块编译，Config 就位于 crate::config::Config。普通的 library 内部导入不应依赖自身的外部 crate 名称。

不同的建议通常来自不同的编译上下文。仅凭两条简化提示，还不能确认项目一定存在重复加载。

检查 main.rs 是否重复声明模块

查看 tool/src/main.rs 是否包含：

mod command;

如果 lib.rs 也声明了：

pub mod command;

那么 command/mod.rs 和 command/cmd_config.rs 可能会分别进入两个 crate 的模块树：

library crate
└── command
    └── cmd_config

binary crate
└── command
    └── cmd_config

如果只有 library 根声明了 config，cmd_config.rs 中的 crate::config 就会在 library 中成立，在 binary 中失败。

即使在 main.rs 中再加上 mod config;，两个目标也会各自定义一份 Config 类型。它们具有不同的类型身份，后续可能出现参数类型不匹配。

如果希望由 library 提供公共功能、binary 负责调用，可以把模块声明统一放在 lib.rs 中，让 main.rs 通过 library 的公开路径调用。

一个可对照的最小结构

以下示例采用 Rust 2018 或更新的 edition，假设 library crate 名称为 tool。为突出导入关系，示例中的 Config 是不带字段的结构体，实际项目应保留原有字段和实现。

tool/
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── main.rs
    ├── config.rs
    └── command/
        ├── mod.rs
        └── cmd_config.rs

src/lib.rs 声明 library 的模块：

pub mod config;
pub mod command;

原有的 pub mod prompt; 可以继续保留，这里省略了与导入关系无关的模块。

src/config.rs：

pub struct Config;

src/command/mod.rs：

pub mod cmd_config;

src/command/cmd_config.rs 在 library 内部使用 crate::：

use crate::config::Config;

pub fn cmd_config(_config: &Config) {
    // 使用配置执行命令。
}

src/main.rs 通过 library crate 名称调用公开功能：

use tool::command::cmd_config::cmd_config;
use tool::config::Config;

fn main() {
    let config = Config;
    cmd_config(&config);
}

在这种组织方式下，模块由 library 管理，main.rs 不再声明 mod command; 或 mod config;。

tool 是这里假设的 library crate 名称。它通常由 package 名称推导，也可以通过 Cargo.toml 的 [lib] name 设置；名称中的连字符在 Rust crate 路径中通常对应下划线。应以项目实际配置为准。

workspace 名称能用作模块路径吗？

不能仅凭 workspace 的名称或目录名称构造导入路径。

例如，根目录叫 alpha，并不意味着可以这样访问成员：

use alpha::tool::config::Config;

workspace 不会自动创建 alpha crate，也不会把成员 package 注册为它的子模块。

如果另一个成员 util 要使用 tool 的公开类型，需要先在 util/Cargo.toml 中声明依赖。假设两个成员目录相邻，且 package 名称确实为 tool，可以写成：

[dependencies]
tool = { path = "../tool" }

然后在 util 的代码中使用：

use tool::config::Config;

仅把两个 package 列入同一个 workspace 的 members，不会自动建立依赖关系。

按编译目标定位实际问题

可以依次检查：

确认错误来自哪个目标：查看完整诊断中的文件位置及编译失败目标，区分 library、binary、测试或示例。
检查模块声明：查看 lib.rs、main.rs、src/bin/ 等入口，确认 command 是否被多个 crate 加载。
核对根模块：crate::config 要求当前 crate 的根声明了 config；同目录下存在 config.rs 文件并不足够。
核对 Cargo.toml：检查 [lib]、[[bin]] 是否设置了不同的名称或入口路径，以及代码使用的 crate 名称是否匹配。

如果 package 名称是 tool，可以先检查 library：

cargo check -p tool --lib

若该 package 存在 binary 目标，再执行：

cargo check -p tool --bins

如果 library 检查通过、binary 检查失败，可以重点查看 binary 的入口和模块声明。

顶层 Cargo.toml 可能影响成员和目标的选择，但 workspace 配置本身不会把 crate::config 改成 tool::config。就已给出的结构而言，应先核对源码实际进入了哪棵模块树，再决定导入路径。