使用 Strapi 进行 TypeScript 开发

¥TypeScript Development with Strapi

本页提供了在 Strapi v5 中使用 TypeScript 进行开发的全面指南，涵盖了有效集成 TypeScript 的关键模式和配置。你将找到有关使用 Strapi 提供的类型、生成和管理内容类型的类型、以编程方式配置 Strapi 以及使用 TypeScript 构建插件的部分。每个部分都包含实用步骤和示例代码，以帮助你在 Strapi 项目中设置和排除基于 TypeScript 的工作流程故障。

¥This page provides a comprehensive guide to developing with TypeScript in Strapi v5, covering key patterns and configurations for integrating TypeScript effectively. You'll find sections on using Strapi’s provided types, generating and managing typings for content types, configuring Strapi programmatically, and building plugins with TypeScript. Each section includes practical steps and example code to help you set up and troubleshoot TypeScript-based workflows in your Strapi project.

🤓 API 参考

我们正在准备一个 API 参考页面，其中将包括 Strapi 导出的类型的详尽列表。请尽快回来！👀

¥We are preparing an API reference page, which will include an exhaustive list of the types exported by Strapi. Please come back soon! 👀

📚指南

¥📚 Guides

指南是你可能需要在应用中使用 Strapi 类型的常见示例的精选列表。

¥The guides are a curated list of common examples in which you might need to use Strapi types in your application.

你可以找到可用指南 此处 的列表。

¥You can find the list of available guides here.

使用 Strapi TypeScript 类型

¥Use Strapi TypeScript typings

Strapi 提供了 Strapi 类上的类型以增强 TypeScript 开发体验。这些类型具有自动补齐功能，可以在开发时自动提供建议。

¥Strapi provides typings on the Strapi class to enhance the TypeScript development experience. These typings come with an autocomplete feature that automatically offers suggestions while developing.

要在开发 Strapi 应用时体验基于 TypeScript 的自动补齐功能，你可以尝试以下操作：

¥To experience TypeScript-based autocomplete while developing Strapi applications, you could try the following:

1. 从你的代码编辑器打开 ./src/index.ts 文件。

   ¥Open the ./src/index.ts file from your code editor.

2. 在全局 register 方法中将 strapi 参数声明为类型 Strapi：

   ¥Declare the strapi argument as type Strapi within the global register method:

   ./src/index.ts

   import type { Core } from '@strapi/strapi';
   
   export default {
     register({ strapi }: { strapi: Core.Strapi }) {
       // ...
     },
   };

3. 在 register 方法的主体中，开始键入 strapi. 并使用键盘箭头浏览可用属性。

   ¥Within the body of the register method, start typing strapi. and use keyboard arrows to browse the available properties.

4. 从列表中选择 runLifecyclesFunctions。

   ¥Choose runLifecyclesFunctions from the list.

5. 添加 strapi.runLifecyclesFunctions 方法后，代码编辑器将返回可用生命周期类型（即 register、bootstrap 和 destroy）的列表。使用键盘箭头选择生命周期之一，代码将自动补齐。

   ¥When the strapi.runLifecyclesFunctions method is added, a list of available lifecycle types (i.e. register, bootstrap and destroy) are returned by the code editor. Use keyboard arrows to choose one of the lifecycles and the code will autocomplete.

为内容类型模式生成类型

¥Generate typings for content-types schemas

要为你的项目模式生成类型，请使用 ts:generate-types CLI 命令。ts:generate-types 命令在项目根目录中创建文件夹 types，其中存储项目的类型。可选的 --debug 标志返回生成的模式的详细表。

¥To generate typings for your project schemas use the ts:generate-types CLI command. The ts:generate-types command creates the folder types, at the project root, which stores the typings for your project. The optional --debug flag returns a detailed table of the generated schemas.

要使用 ts:generate-types，请在项目根目录的终端中运行以下代码：

¥To use ts:generate-typesrun the following code in a terminal at the project root:

npm

npm run strapi ts:generate-types --debug #optional flag to display additional logging

yarn

yarn strapi ts:generate-types --debug #optional flag to display additional logging

💡 提示：自动生成类型

通过将 autogenerate: true 添加到 config/typescript.js|ts 配置文件，可以在服务器重启时自动生成类型。

¥Types can be automatically generated on server restart by adding autogenerate: true to the config/typescript.js|ts configuration file.

💡 提示：在前端应用中使用类型

要在前端应用中使用 Strapi 类型，你可以 使用解决方法，直到 Strapi 实现官方解决方案。

¥To use Strapi types in your front-end application, you can use a workaround until Strapi implements an official solution.

修复生成类型的构建问题

¥Fix build issues with the generated types

可以排除生成的类型，以便实体服务不使用它们，而是使用不检查内容类型中可用的实际属性的宽松类型。

¥The generated types can be excluded so that the Entity Service doesn't use them and falls back on looser types that don't check the actual properties available in the content types.

为此，请编辑 Strapi 项目的 tsconfig.json 并将 types/generated/** 添加到 exclude 数组：

¥To do that, edit the tsconfig.json of the Strapi project and add types/generated/** to the exclude array:

./tsconfig.json

  // ...
  "exclude": [
    "node_modules/",
    "build/",
    "dist/",
    ".cache/",
    ".tmp/",
    "src/admin/",
    "**/*.test.ts",
    "src/plugins/**",
    "types/generated/**"
  ]
  // ...

但是，如果你仍想在项目中使用生成的类型，但又不想让 Strapi 使用它们，则一种解决方法是复制这些生成的类型并将它们粘贴到 generated 目录之外（以便在重新生成类型时不会覆盖它们）并从文件底部删除 declare module '@strapi/types'。

¥However, if you still want to use the generated types on your project, but don't want Strapi to use them, a workaround could be to copy those generated types and paste them outside of the generated directory (so that they aren't overwritten when the types are regenerated) and remove the declare module '@strapi/types' from the bottom of the file.

⚠️ 警告

类型只能从 @strapi/strapi 导入，以避免重大更改。@strapi/types 中的类型仅供内部使用，可能会更改，恕不另行通知。

¥Types should only be imported from @strapi/strapi to avoid breaking changes. The types in @strapi/types are for internal use only and may change without notice.

以编程方式启动 Strapi

¥Start Strapi programmatically

要在 TypeScript 项目中以编程方式启动 Strapi，Strapi 实例需要已编译的代码位置。本节介绍如何设置和指示编译后的代码目录。

¥To start Strapi programmatically in a TypeScript project the Strapi instance requires the compiled code location. This section describes how to set and indicate the compiled code directory.

使用 createStrapi() 工厂

¥Use the createStrapi() factory

Strapi 可以使用 strapi.createStrapi() 工厂以编程方式运行。由于 TypeScript 项目的代码是在特定目录中编译的，因此应将参数 distDir 传递给工厂以指示应在何处读取编译后的代码：

¥Strapi can be run programmatically by using the strapi.createStrapi() factory. Since the code of TypeScript projects is compiled in a specific directory, the parameter distDir should be passed to the factory to indicate where the compiled code should be read:

./server.js

const strapi = require('@strapi/strapi');




const app = strapi.createStrapi({ distDir: './dist' });


app.start();

使用 strapi.compile() 功能

¥Use the strapi.compile() function

strapi.compile() 函数应该主要用于开发需要启动 Strapi 实例并检测项目是否包含 TypeScript 代码的工具。strapi.compile() 自动检测项目语言。如果项目代码包含任何 TypeScript 代码，strapi.compile() 会编译该代码并返回一个上下文，其中包含 Strapi 所需目录的特定值：

¥The strapi.compile() function should be mostly used for developing tools that need to start a Strapi instance and detect whether the project includes TypeScript code. strapi.compile() automatically detects the project language. If the project code contains any TypeScript code, strapi.compile() compiles the code and returns a context with specific values for the directories that Strapi requires:

const strapi = require('@strapi/strapi');



strapi.compile().then((appContext) => strapi(appContext).start());

使用 TypeScript 开发插件

¥Develop a plugin using TypeScript

可以在 插件开发文档 之后生成新插件，确保在 CLI 工具提示时选择 "TypeScript"。

¥New plugins can be generated following the plugins development documentation, ensuring you select "TypeScript" when prompted by the CLI tool.

TypeScript 应用有两个重要的区别：

¥There are 2 important distinctions for TypeScript applications:

• 创建插件后，在插件目录 src/admin/plugins/[my-plugin-name] 中运行 yarn 或 npm install 来安装插件的依赖。

  ¥After creating the plugin, run yarn or npm install in the plugin directory src/admin/plugins/[my-plugin-name] to install the dependencies for the plugin.

• 在插件目录 src/admin/plugins/[my-plugin-name] 中运行 yarn build 或 npm run build 以构建包含插件的管理面板。

  ¥Run yarn build or npm run build in the plugin directory src/admin/plugins/[my-plugin-name] to build the admin panel including the plugin.

✏️ 注意

初次安装后无需重复执行 yarn 或 npm install 命令。yarn build 或 npm run build 命令是实现影响管理面板的任何插件开发所必需的。

¥It is not necessary to repeat the yarn or npm install command after the initial installation. The yarn build or npm run build command is necessary to implement any plugin development that affects the admin panel.