Strapi 客户端

页面摘要： Strapi 客户端是一个 JavaScript 库，通过 collection()、single() 和 files() 方法简化了与 Strapi 后端的交互，用于获取、创建、更新和删除内容。

Strapi 客户端库简化了与 Strapi 后端的交互，提供了一种获取、创建、更新和删除内容的方式。本指南将引导你完成 Strapi 客户端的设置、身份验证配置，以及如何有效使用其关键功能。

入门

安装

要在项目中使用 Strapi 客户端，请使用你偏好的包管理器将其作为依赖安装：

Yarn

yarn add @strapi/client

NPM

npm install @strapi/client

pnpm

  pnpm add @strapi/client

基础配置

要开始与 Strapi 后端交互，请初始化 Strapi 客户端并设置基础 API URL：

JavaScript

使用 Javascript 时，导入 strapi 函数并创建一个客户端实例：

import { strapi } from '@strapi/client';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

TypeScript

使用 Typescript 时，导入 strapi 函数并使用你的 Strapi API 基础 URL 创建一个客户端实例：

import { strapi } from '@strapi/client';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

Browser (UMD) 如果你在浏览器环境中使用 Strapi 客户端，可以通过 <script> 标签引入。

<script src="https://cdn.jsdelivr.net/npm/@strapi/client"></script>

<script>
  const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
</script>

baseURL 必须包含协议（http 或 https）。无效的 URL 会抛出 StrapiInitializationError 错误。

身份验证

Strapi 客户端支持多种身份验证策略，用于访问 Strapi 后端中受保护的资源。

如果你的 Strapi 实例使用 API 令牌，请按如下方式配置 Strapi 客户端：

const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token-here',
});

这样可使你的请求自动包含必要的身份验证凭据。如果令牌无效或缺失，客户端会在初始化时抛出 StrapiValidationError 错误。

API 参考

Strapi 客户端提供以下用于与 Strapi 后端交互的关键属性和方法：

通用 fetch

Strapi 客户端提供对底层 JavaScript fetch 函数的访问，用于直接发起 API 请求。该请求始终相对于客户端初始化时提供的基础 URL：

const result = await client.fetch('articles', { method: 'GET' });

使用集合类型

Strapi 中的集合类型是拥有多个条目（entry）的实体（例如拥有多篇文章的博客）。Strapi 客户端提供 collection() 方法用于与这些资源交互，可用方法如下：

用法示例：

JavaScript

const articles = client.collection('articles');

// 获取所有按标题排序的英文文章
const allArticles = await articles.find({
  locale: 'en',
  sort: 'title',
});

// 获取单篇文章
const singleArticle = await articles.findOne('article-document-id');

// 创建新文章
const newArticle = await articles.create({ title: 'New Article', content: '...' });

// 更新已有文章
const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });

// 删除文章
await articles.delete('article-id');

使用单一类型

Strapi 中的单一类型表示仅存在一次的独有内容条目（例如首页设置或全站配置）。Strapi 客户端提供 single() 方法用于与这些资源交互，可用方法如下： | Parameter | Description | | ----------| -------------------------------------------------------------------------------------------- | | find(queryParams?) | 获取该文档。 | | update(documentID, data, queryParams?) | 更新该文档。 | | delete(queryParams?) | 删除该文档。 |

用法示例：

const homepage = client.single('homepage');

// 获取默认首页内容
const defaultHomepage = await homepage.find();

// 获取西班牙语版本的首页
const spanishHomepage = await homepage.find({ locale: 'es' });

// 更新首页草稿内容
const updatedHomepage = await homepage.update(
  { title: 'Updated Homepage Title' },
  { status: 'draft' }
);

// 删除首页内容
await homepage.delete();

使用文件

Strapi 客户端通过 files 属性提供对 媒体库 的访问。这使你能够检索和管理文件元数据，而无需直接与 REST API 交互。

以下方法可用于处理文件。点击表格中的方法名可跳转到对应章节，查看更详细的说明和示例：

find

strapi.client.files.find() 方法根据可选的查询参数检索文件元数据列表。

该方法的使用方式如下：

// 初始化客户端
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// 查找所有文件元数据
const allFiles = await client.files.find();
console.log(allFiles);

// 使用过滤和排序查找文件元数据
const imageFiles = await client.files.find({
  filters: {
    mime: { $contains: 'image' }, // 仅获取图片文件
    name: { $contains: 'avatar' }, // 仅获取名称中包含 'avatar' 的文件
  },
  sort: ['name:asc'], // 按名称升序排序
});

findOne {#findone}

strapi.client.files.findOne() 方法根据文件 ID 检索单个文件的元数据。

该方法的使用方式如下：

// 初始化客户端
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// 根据 ID 查找文件元数据
const file = await client.files.findOne(1);
console.log(file.name);
console.log(file.url); 
console.log(file.mime); // 文件 MIME 类型

update

strapi.client.files.update() 方法更新已有文件的元数据，接受 2 个参数：fileId 以及一个包含 name、alternativeText（替代文本）和 caption（说明文字）等选项的对象。

该方法的使用方式如下：

// 初始化客户端
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// 更新文件元数据
const updatedFile = await client.files.update(1, {
  name: 'New file name',
  alternativeText: 'Descriptive alt text for accessibility',
  caption: 'A caption for the file',
});

upload （新增） {#upload}

Strapi 客户端通过 FilesManager 提供媒体文件上传功能，可通过 strapi.client.files.upload() 方法访问。该方法允许你向 Strapi 后端上传媒体文件（如图片、视频或文档）。

该方法支持以 Blob（在浏览器或 Node.js 中）或 Buffer（仅限 Node.js）形式上传文件。该方法还支持为上传的文件附加元数据，例如 alternativeText 和 caption。

方法签名

async upload(file: Blob, options?: BlobUploadOptions): Promise<MediaUploadResponse>
async upload(file: Buffer, options: BufferUploadOptions): Promise<MediaUploadResponse>

• 对于 Blob 上传，options 为可选，可包含用于元数据的 fileInfo。
• 对于 Buffer 上传，options 必须包含 filename 和 mimetype，并可包含 fileInfo。

响应是一个文件对象数组，每个对象包含 id、name、url、size 和 mime 等详细信息 source。

Upload a file with the browser

你可以通过浏览器上传文件，方式如下：

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

try {
  const result = await client.files.upload(file, {
    fileInfo: {
      alternativeText: 'A user uploaded image',
      caption: 'Uploaded via browser',
    },
  });
  console.log('Upload successful:', result);
} catch (error) {
  console.error('Upload failed:', error);
}

Upload a file with Node.js

在 Node.js 中，你可以上传 blob 或 buffer，如下所示：

Uploading a Blob

import { readFile } from 'fs/promises';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const filePath = './image.png';
const mimeType = 'image/png';
const fileContentBuffer = await readFile(filePath);
const fileBlob = new Blob([fileContentBuffer], { type: mimeType });

try {
  const result = await client.files.upload(fileBlob, {
    fileInfo: {
      name: 'Image uploaded as Blob',
      alternativeText: 'Uploaded from Node.js Blob',
      caption: 'Example upload',
    },
  });
  console.log('Blob upload successful:', result);
} catch (error) {
  console.error('Blob upload failed:', error);
}

Uploading a Buffer

import { readFile } from 'fs/promises';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

const filePath = './image.png';
const fileContentBuffer = await readFile(filePath);

try {
  const result = await client.files.upload(fileContentBuffer, {
    filename: 'image.png',
    mimetype: 'image/png',
    fileInfo: {
      name: 'Image uploaded as Buffer',
      alternativeText: 'Uploaded from Node.js Buffer',
      caption: 'Example upload',
    },
  });
  console.log('Buffer upload successful:', result);
} catch (error) {
  console.error('Buffer upload failed:', error);
}

响应结构

strapi.client.files.upload() 方法返回一个文件对象数组，每个对象包含如下字段：

{
  "id": 1,
  "name": "image.png",
  "alternativeText": "Uploaded from Node.js Buffer",
  "caption": "Example upload",
  "mime": "image/png",
  "url": "/uploads/image.png",
  "size": 12345,
  "createdAt": "2025-07-23T12:34:56.789Z",
  "updatedAt": "2025-07-23T12:34:56.789Z"
}

delete

strapi.client.files.delete() 方法根据文件 ID 删除文件。

该方法的使用方式如下：

// 初始化客户端
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// 根据 ID 删除文件
const deletedFile = await client.files.delete(1);
console.log('File deleted successfully');
console.log('Deleted file ID:', deletedFile.id);
console.log('Deleted file name:', deletedFile.name);

处理常见错误

通过 Strapi 客户端发送查询时，可能会出现以下错误：