# @fourlights/strapi-plugin-deep-populate 中文文档

规范地址：https://npmcn.com/package/%40fourlights/strapi-plugin-deep-populate/

版本：1\.17\.1
npm 元数据更新时间：2026-09-17T09:46:39.903Z
中文译文更新时间：2026-11-15T10:23:08.754Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fourlights/strapi-plugin-deep-populate
原文对照：https://npmcn.com/package/%40fourlights/strapi-plugin-deep-populate/?lang=original
项目主页：https://github.com/Four-Lights-NL/strapi-plugin-deep-populate#readme

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@strapi/sdk-plugin ^5，@strapi/strapi ^5
- 首次发布：2025-01-22T20:07:08.313Z
- 最新版本发布：2026-09-17T09:46:39.551Z
- 近 30 天下载量：3786（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 20 个）

## 中文简介

这个插件提供了在单个请求中检索所有被嵌入对象的简单方式.

## 安装

```sh
npm install @fourlights/strapi-plugin-deep-populate
```

也可以使用：`pnpm add @fourlights/strapi-plugin-deep-populate`、`yarn add @fourlights/strapi-plugin-deep-populate`、`bun add @fourlights/strapi-plugin-deep-populate`

## README

# Strapi v5 深插件

[![npm version](https://badge.fury.io/js/@fourlights%2Fstrapi-plugin-deep-populate.svg)](https://badge.fury.io/js/@fourlights%2Fstrapi-plugin-deep-populate)

Strapi v5 插件, 它会自动在单个请求中填充所有嵌入式关系 `populate: '*'`。 。 。 . 它不会对筑巢水平施加限制,并且可以缓存聚居对象来改进性能.

## 特征

-   自动解决并填充所有嵌入式关系
-   支持包括动态区域在内的所有关系类型
-   处理循环参考和边缘案例
-   包括为改进业绩而进行的缓存
-   荣誉 `populateCreatorFields` 设置
-   支持可选性 允许/ 拒绝列表, 用于人群中的特定关系或组件

## 安装

```bash
npm install @fourlights/strapi-plugin-deep-populate
```

## 使用量

在您的 Strapi 配置中启用深层人口 :

```js
// config/plugins.js
module.exports = ({ env }) => ({
  'deep-populate': {
    enabled: true,
    config: {
      useCache: true, // default
      replaceWildcard: true, // default
    }
  }
});
```

### 基本用途

```ts
// Get fully populated document
const document = await strapi.documents("api.page.page").findOne({
  documentId: 'xyz',
  populate: '*'
});
```

### 高级使用

```ts
// Get populate object for custom usage
const populate = await strapi.plugin("deep-populate")
  .service("populate")
  .get({
    documentId: 'xyz',
    contentType: 'api::page.page',
    omitEmpty: true // optional
  });

const document = await strapi.documents('api::page.page').findOne({
  documentId: 'xyz',
  populate
});
```

### 省略Empty和本地化

插件提供了精细的控件, 通过 : `omitEmpty` 财务报告和审定财务报表 `localizations` 选项.

#### 全局配置

设定所有内容类型的默认行为 :

```js
// config/plugins.js
module.exports = ({ env }) => ({
  'deep-populate': {
    enabled: true,
    config: {
      useCache: true,
      replaceWildcard: true,
      omitEmpty: true, // Omit empty attributes by default
      localizations: false, // Exclude localizations by default
    }
  }
});
```

#### 内容- 类型特定配置

覆盖特定内容类型的全局设置 :

```js
// config/plugins.js
module.exports = ({ env }) => ({
  'deep-populate': {
    enabled: true,
    config: {
      useCache: true,
      replaceWildcard: true,
      omitEmpty: true,
      localizations: false,
      
      contentTypes: {
        'api::page.page': {
          omitEmpty: false, // Include all attributes for pages
          localizations: true, // Always include localizations for pages
        },
        'api::blog-post.blog-post': {
          omitEmpty: true, // Explicitly omit empty attributes
          localizations: true, // But include localizations for blog posts
        }
      }
    }
  }
});
```

#### 函数参数配置

每个请求覆盖全局和内容类型设置 :

```ts
// Get populate object with custom settings
const populate = await strapi.plugin("deep-populate")
  .service("populate")
  .get({
    documentId: 'xyz',
    contentType: 'api::page.page',
    omitEmpty: true, // Override content-type setting
    localizations: false // Override content-type setting
  });
```

#### 覆盖优先级

按下列优先排序(最高至最低)应用设置:

1.  **函数参数** - 直接传给了 `get()` 方法
2.  **内容类型配置** - 具体内容类型
3.  **全球配置** - 默认插件设置

#### 特殊行为

-   何时 `localizations: true`,即使 `omitEmpty: true`
-   何时 `localizations: false`中,将本地化排除在外,而不论 `omitEmpty` 设置
-   这个 `localizations` 选项只影响已启用 i18n 的内容类型

### 缓存

插件缓存会填充对象以提高性能. 可禁用缓存 通过 `useCache` 设置。 数据库中持续保存缓存全集,并可以 在内容类型更新后变得僵化。 你可以用这个 `cacheOptions > clearCacheOnStartup` 以强制在服务器启动时进行缓存清理.

#### 快取配置

```js
// config/plugins.js
module.exports = ({ env }) => ({
  'deep-populate': {
    enabled: true,
    config: {
      useCache: true, // Enable caching (default: true)
      cacheOptions: {
        clearCacheOnStartup: false, // Clear cache on server startup (default: false)
        warmOnWrite: false, // Re-warm cache synchronously after writes; NOTE: can be slow (default: false)
      }
    }
  }
});
```

### 创建者字段

插件自动填充 `createdBy` 财务报告和审定财务报表 `updatedBy` 字段时 `populateCreatorFields` 在内容类型配置中启用.

### 允许/ 拒绝列表

有时,你可能想要限制某些关系或组成部分的嵌入群. 例如,如果你有一个 `Page` 深筑巢穴的温度 `Link` 组件与另一个 `Page`。 。 。 . 在这种情况下,您可以使用许可列表或拒绝列表来控制插件应该停止解决嵌入关系的地方.

```ts
// config/plugins.js
module.exports = ({ env }) => ({
  'deep-populate': {
    enabled: true,
    config: {
      useCache: true,
      replaceWildcard: true,
      
      contentTypes: {
        // '*' would apply to all content types
        'api::page.page': {
          deny: {
            relations: ['api::page.page']  // prevent resolving nested pages when populating a page
            // alternatively we could have denied the link component in this case
            // components: ['shared.link']
          }
        }
      }
    }
  }
});
```

* * *

## 插件如何工作

插件递归 :

1.  扭曲内容类型方案
2.  获取带有一层深聚的文档
3.  解决所有嵌入式关系
4.  返回完整的填充对象

这一过程处理所有关系类型,包括动态区和循环引用.

* * *

## 解决问题

由于斯特拉皮的活泼性, 东西变得相当快 并且有时会变得很困难 通过树木看到谚语森林. 那样的话,就随便开口吧 我会尽力帮你的.

但是,首先,确保你:

1.  使用该插件的最新版本
2.  使用 Strapi 的最新版本
3.  查看是否解除缓存解决了问题
4.  检查您的内容类型是否仍然有效, 例如, 没有引用已删除组件的动态区域 .
5.  请检查access-date=中的日期值 (帮助) API 响应中您没有标为私有属性/关系

如果那样的话,就把问题打开! 确保您报告所使用的版本( plugin & pidei) , 并最好共享受影响的内容类型定义 。 或更好, 复制问题.

* * *

## 恒星历史

[![Star History Chart](https://api.star-history.com/svg?repos=Four-Lights-NL/strapi-plugin-deep-populate&type=date&legend=top-left)](https://www.star-history.com/#Four-Lights-NL/strapi-plugin-deep-populate&type=date&legend=top-left)

感谢阅读和使用插件. 如果你喜欢的话,就考虑当主演 给我一个漂亮的多巴胺打击下一次我的工作.

### 由 QQ 创建 [开发, NL](https://en.wikipedia.org/wiki/Deventer)。 。 。 .

## 常见问题

### @fourlights/strapi-plugin-deep-populate 是什么？

这个插件提供了在单个请求中检索所有被嵌入对象的简单方式\.

### 如何安装 @fourlights/strapi-plugin-deep-populate？

在项目目录运行 npm install @fourlights/strapi-plugin-deep-populate，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@strapi/sdk-plugin（^5）、@strapi/strapi（^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fourlights/strapi-plugin-deep-populate 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fourlights/strapi-plugin-deep-populate 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fourlights/strapi-plugin-deep-populate 可以商用吗？

@fourlights/strapi-plugin-deep-populate 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fourlights/strapi-plugin-deep-populate 的下载量有多少？

根据 npm 官方下载统计，@fourlights/strapi-plugin-deep-populate 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,786 次，日均约 126 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fourlights/strapi-plugin-deep-populate 还在维护吗？

最新版本 1\.17\.1 发布于 2026/09/17（1 个月前）；至今共发布 60 个版本，其中过去 12 个月发布了 20 个；首次发布于 2025/01/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。