Strapi 部署避坑指南：Git 冲突、数据迁移与构建优化

问题一：Git 拉取时提示本地文件被修改

现象

在服务器上执行 git pull 时，经常遇到以下错误：

error: Your local changes to the following files would be overwritten by merge:
        src/extensions/documentation/documentation/1.0.0/full_documentation.json
Please commit your changes or stash them before you merge.
Aborting

原因

full_documentation.json 是 Strapi 自动生成的 API 文档文件。每次 Strapi 启动或构建时，都会根据当前的内容类型重新生成该文件。由于服务器和本地的启动时间不同，生成的文件内容会有细微差异，导致 Git 认为文件被修改。

解决方案

将自动生成的文件加入 .gitignore：

# 自动生成的文档（每次启动/构建时重新生成，不需要提交）
src/extensions/documentation/documentation/

# 其他常见的自动生成文件
.strapi/
.tmp/
build/

操作步骤：

1. 本地修改 .gitignore 并提交推送
2. 服务器上先暂存本地修改再拉取：

git stash          # 暂存本地修改
git pull           # 拉取远程代码
git stash drop     # 丢弃暂存的本地修改（因为是自动生成的，可以安全丢弃）

其他可能冲突的自动生成文件

类似的情况还可能出现在以下文件：

• .strapi/ 目录
• .tmp/ 目录
• package-lock.json（跨平台环境可能格式不同）

建议一并加入 .gitignore。

---

问题二：数据导入导出插件无法使用

现象

使用第三方插件 strapi-import-export 导出数据后，导入时页面显示加载动画，转一会儿后没有任何反应，数据也没有导入成功，且没有任何错误提示。

原因

strapi-import-export@0.0.1 是一个实验性插件，与 Strapi 5 不兼容。该插件版本过低，API 已经变更，导致导入功能静默失败。

解决方案

移除不兼容的第三方插件，使用 Strapi 官方内置的 DTS（Data Transfer System）工具。

1. 修改 package.json

移除第三方插件依赖：

{
  "dependencies": {
    // 删除这行
    // "strapi-import-export": "^0.0.1"
  },
  "scripts": {
    "export": "strapi export --no-encrypt -f backup",
    "export:content": "strapi export --no-encrypt -f backup --only content",
    "import": "strapi import --force"
  }
}

2. 导出数据（本地）

cd strapi

# 导出全部内容（含媒体文件）
npm run export

# 或只导出内容数据（不含媒体文件）
npm run export:content

导出后会生成 backup.tar.gz 文件。

3. 导入数据（服务器）

# 1. 将 backup.tar.gz 上传到服务器 strapi 目录

# 2. 停止 Strapi 服务
pm2 stop strapi  # 或你的进程管理命令

# 3. 导入数据（注意使用 --file 或 -f 参数）
npm run import -- --file ./backup.tar.gz

# 4. 重启服务
pm2 start strapi

注意： 导入前必须先停止 Strapi 服务，否则可能导致数据冲突。

---

问题三：构建时 public 目录被复制到 build 目录

现象

执行 strapi build 后，build 目录中包含了 public/uploads 中的所有图片文件，导致构建产物体积很大。

原因

这是 Strapi 5 的默认行为。strapi build 会将 public 目录复制到 build 目录中，目的是让生产环境（npm run start）能正确提供静态文件（上传的图片等）。

是否需要优化？

这是正常且必要的行为。 生产模式下，Strapi 从 build 目录提供静态资源，如果 build 中没有 uploads，上传的图片将无法访问。

可选优化方案

方案一：使用云存储（推荐）

将图片上传到阿里云 OSS、腾讯云 COS、七牛云等对象存储服务，不存储在本地服务器。需要安装对应的 Strapi 上传插件。

方案二：代码未变时不重新构建

如果只是同步数据，代码没有修改，不需要重新构建：

# 直接使用已有的 build 目录
npm run start

方案三：优化构建内存

如果服务器内存较小（如 2GB），构建时可能卡死。可以增加内存限制：

{
  "scripts": {
    "build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" strapi build"
  }
}

---

问题四：管理面板语言只有英文没有中文

现象

部署到服务器后，Strapi 管理面板的语言选择器中只有 English，没有简体中文。

原因

服务器上的 src/admin/app.tsx 文件没有更新，或者没有重新构建管理面板。

解决方案

1. 确认代码已更新

   确保 src/admin/app.tsx 包含中文翻译配置：

   export default {
     config: {
       locales: ['en', 'zh-Hans'],
       translations: {
         'zh-Hans': {
           // ... 翻译配置
         }
       }
     }
   }

2. 重新构建管理面板

   cd strapi
   npm run build
   pm2 restart strapi

3. 清除浏览器缓存

   管理面板的语言设置可能缓存在 localStorage 中，清除缓存后重新登录。

---

总结

问题	原因	解决方案
Git 拉取冲突	自动生成文件被提交到仓库	加入 .gitignore
数据导入失败	第三方插件不兼容	使用官方 DTS 工具
构建产物过大	public 目录被复制	正常行为，可用云存储优化
管理面板无中文	代码未更新或未重新构建	更新代码并重新构建

核心建议：

• 不要提交自动生成的文件到 Git 仓库
• 使用官方工具而非第三方实验性插件
• 部署前先停服务，导入数据后再重启
• 代码未变时无需重新构建，直接启动即可