Strapi 指南

一、前言

1.1 文档背景

本人有随手记录知识点的习惯，比如在遇见一些问题的时候顺手记录错误与解决方案等等。想想存着也是存着，提供课程之余也顺便发出来分享给宝子们；而且课程指南由于具备实效性，编辑起来非常麻烦，但是大体流程在后续版本更新中变更也不大，所以干脆放在这里统一管理更新后适用的知识点。

本文档的完善程度较低，于未来的一段时间内仍有较大改动，敬请期待。

二、知识点

2.1 页面简介

2.2 数据类型

2.3 常用过滤操作符

2.4 分页参数详解

三、故障排查

3.1 常见错误

启动相关错误：

• ⠸ Loading Strapi[ERROR] There seems to be an unexpected error, try again with --debug for more information

  • 解决方案： 使用 yarn develop --debug 或 npm run develop -- --debug 获取详细错误信息
  • 常见原因： 数据库连接失败、端口被占用、依赖包版本冲突

• Error: listen EADDRINUSE: address already in use :::1337

  • 解决方案： 端口被占用，使用 lsof -i :1337 查找占用进程，或修改 .env 中的 PORT 配置

• Module not found: Can't resolve '@strapi/design-system'

  • 解决方案： 删除 node_modules 和 package-lock.json，重新安装依赖

  代码已复制！
  rm -rf node_modules package-lock.json
  npm install

数据库相关错误：

• ER_ACCESS_DENIED_ERROR: Access denied for user

  • 解决方案： 检查 .env 中的数据库用户名密码，确保用户有足够权限
  • 权限检查： 用户需要 CREATE, ALTER, DROP, SELECT, INSERT, UPDATE, DELETE 权限

• Database connection error: Unknown database

  • 解决方案： 手动创建数据库，或确保 Strapi 用户有创建数据库的权限

  代码已复制！
  CREATE DATABASE your_database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

• ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol

  • 解决方案： MySQL 8.0 认证问题，需要修改用户认证方式

  代码已复制！
  ALTER USER 'your_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
  FLUSH PRIVILEGES;

3.2 常见问题

• Q: 我要修改 Strapi 连接的数据库，以及其用户名与密码，可我不知道它在哪里

  • 在 Strapi 项目的根目录下有一个 .env 文件，除了配置连接数据库以及账号密码以外，服务器的 ip 与端口，以及数据库的客户端类型、ip、端口与开关 SSL 连接都是在这里配置的。

• Q: 如何修改 Strapi 的数据库连接配置？

  • A: 编辑项目根目录下的 .env 文件，修改以下配置：

  代码已复制！
  DATABASE_CLIENT=mysql
  DATABASE_HOST=127.0.0.1
  DATABASE_PORT=3306
  DATABASE_NAME=your_database_name
  DATABASE_USERNAME=your_username
  DATABASE_PASSWORD=your_password
  DATABASE_SSL=false

• Q: 如何更改 Strapi 的默认端口？

  • A: 在 .env 文件中添加或修改：

  代码已复制！
  PORT=1338
  HOST=0.0.0.0

• Q: 忘记了管理员密码怎么办？

  • A: 可以通过数据库直接重置，或使用以下命令：

  代码已复制！
  yarn run strapi admin:reset-user-password --email=admin@example.com
  # 或使用 npm
  npm run strapi admin:reset-user-password --email=admin@example.com

3.3 API 报错

3.4 性能和优化问题

常见性能问题：

• Q: API 响应慢？

  • A: 检查以下几点：
    1. 使用 populate 时避免过深的嵌套
    2. 使用 fields 参数只获取需要的字段
    3. 合理使用分页参数
    4. 为常用查询字段添加数据库索引

• Q: 内存占用过高？

  • A:
    1. 检查是否有内存泄漏
    2. 优化图片上传大小
    3. 使用 CDN 存储媒体文件
    4. 定期清理日志文件

最佳实践建议：

代码已复制！
// ❌ 不推荐：获取所有数据和关联
const badQuery = '/api/articles?populate=*';

// ✅ 推荐：只获取需要的字段和关联
const goodQuery = '/api/articles?fields[0]=title&fields[1]=slug&populate[author][fields][0]=name&pagination[pageSize]=10';

（未完待续...）