从Git仓库拉取后Strapi后台媒体文件不显示问题求助

问题根源 #

Strapi的媒体库不仅依赖public/uploads文件夹里的物理文件，还需要数据库中plugin::upload.file表的元数据记录（包括文件路径、名称、关联资源等）。你只同步了物理文件，数据库里的对应记录没同步，所以后台面板看不到文件，资源的Image字段也为空。

开发环境多电脑同步解决方案 #

方案1：同步数据库（最简单直接） #

如果用SQLite作为开发数据库：

• 找到项目中的SQLite数据库文件（默认路径是./.tmp/data.db，自定义过路径请对应调整），将其添加到Git仓库。
• 后续执行git pull时，数据库文件会同步到本地，媒体文件的元数据记录也会随之同步，后台就能正常显示文件，资源的Image字段也能关联上。

如果用MySQL/PostgreSQL等数据库：

• 每次在一台电脑上修改后，导出plugin::upload.file表的数据（比如用MySQL的mysqldump命令），将导出的SQL文件加入Git。
• 拉取代码后，将SQL文件导入本地数据库，完成元数据同步。

方案2：手动重建媒体库索引（无需同步整个数据库） #

如果不想同步数据库，可通过自定义脚本扫描public/uploads文件夹，自动生成数据库元数据记录：

1. 在项目根目录创建scripts/sync-media.js文件，写入以下代码：

const fs = require('fs');
const path = require('path');
const mime = require('mime-types'); // 需要先安装：npm install mime-types
const strapi = require('@strapi/strapi');

async function syncMediaFiles() {
  await strapi().load();
  const uploadDir = path.join(process.cwd(), 'public', 'uploads');

  // 遍历uploads文件夹下的所有文件（含子目录）
  const scanFiles = async (dir) => {
    const items = fs.readdirSync(dir, { withFileTypes: true });
    for (const item of items) {
      const fullPath = path.join(dir, item.name);
      if (item.isDirectory()) {
        await scanFiles(fullPath);
        continue;
      }

      // 检查文件是否已存在于数据库
      const relativePath = path.relative(uploadDir, fullPath).replace(/\\/g, '/');
      const existingFile = await strapi.db.query('plugin::upload.file').findOne({
        where: { url: `/uploads/${relativePath}` }
      });

      if (!existingFile) {
        const fileStats = fs.statSync(fullPath);
        // 创建数据库元数据记录
        await strapi.db.query('plugin::upload.file').create({
          data: {
            name: item.name,
            hash: path.parse(item.name).name, // 用文件名前缀作为hash（简化处理，Strapi原生为随机hash）
            ext: path.extname(item.name),
            mime: mime.lookup(fullPath) || 'application/octet-stream',
            size: fileStats.size,
            url: `/uploads/${relativePath}`,
            provider: 'local',
            provider_metadata: null,
          }
        });
        console.log(`已添加记录: ${relativePath}`);
      }
    }
  };

  await scanFiles(uploadDir);
  console.log('媒体文件元数据同步完成');
  process.exit(0);
}

syncMediaFiles();

2. 安装依赖：npm install mime-types
3. 执行脚本：node scripts/sync-media.js
   执行完成后，数据库会生成所有物理文件的元数据记录，后台面板就能看到媒体文件，资源的Image字段也能恢复关联。

生产环境部署注意事项 #

1. 配置本地存储：确保config/plugins.js中的upload插件配置正确，使用local存储：

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'local',
      providerOptions: {
        sizeLimit: 10 * 1024 * 1024, // 调整为你需要的文件大小限制（这里是10MB）
      },
    },
  },
});

2. 同步文件与元数据：

• 部署时，将public/uploads文件夹和代码一起部署到生产服务器。
• 将开发环境中plugin::upload.file表的元数据导出，导入到生产数据库（比如用数据库导出工具生成SQL，再执行导入）。

3. 权限检查：确保生产服务器上public/uploads文件夹的权限正确，Strapi进程有读写权限。

内容的提问来源于stack exchange，提问作者bjornfas