$project（投影）
最后更新：2026-10-09
$project（投影）
$project 是管道的投影阶段，从文档中选择或排除字段，或用表达式计算新字段输出，把每个文档映射为只包含指定字段的新文档。与 $addFields 不同，$project 默认只输出 _id 和显式列出的字段：传 1 包含、传 0 排除，传表达式则生成新字段。适合缩小文档体积、重命名字段、展平内嵌对象。注意同一投影中不能混用包含与排除（_id 除外）。
| 分类 | 核心阶段 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $project: { <字段>: <1 或 0 或 表达式>, ... } }⚙️ 参数
| 字段投影 | 字段名映射为 1（包含）、0（排除）或聚合表达式（计算新字段）。 |
|---|
返回值：投影后的文档流
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $project：只保留 name，并计算总价
db.orders.aggregate([
{ $project: { _id: 0, name: 1, total: { $multiply: ['$price', '$qty'] } } }
])运行结果：
// 每个文档只剩 name 与 total
{ "name": "Pen", "total": 150 }
{ "name": "Book", "total": 30 }📌 注意事项
- $project 是白名单模式：未列出的字段默认丢弃
- 包含与排除不能混用（_id 除外），混用会报错
- 用点号路径（如 'detail.price'）可重命名或展平内嵌字段
🏷️ 相关标签
💡 相关案例
聚合管道进阶：复杂表达式与转换
聚合管道入门：aggregate方法与基础阶段
实战：博客评论系统CRUD
Change Streams：实时变更监听
$facet + $bucket + 文本/地理空间搜索
$lookup与多集合关联
📚 相关教程
❓ 常见问题
Q$project 和 $addFields 有什么区别？
A$addFields 保留所有原字段并新增字段；$project 默认丢弃未列出的字段，用于裁剪或重建文档结构。
Q$project 能一次排除多个字段吗？
A可以，全部传 0 即可，如 { $project: { secret: 0, log: 0 } }，此时其他字段全部保留。
Q$project 会改变字段顺序吗？
A输出字段按投影中定义的顺序排列，与原始文档中的顺序无关。
