14. 安装和使用出问题怎么办

先找你看到的那句话（红字报错、空白页、少了菜单），照"怎么办"一步步做。每一条都来自真实安装中遇到过的问题。做完还不行，把报错原文（或截图）发到 [email protected]，我们会帮你，并把这个问题补进本页，下一个客人就能自己解决。

动命令之前：先备份（数据库导出 + 复制 app/code 目录），不要在没备份的正式商店上试。

一、安装的时候

1. 安装停在 "You do not have the SUPER privilege and binary logging is enabled"

原因： 你的 MySQL 开了"二进制日志"，Magento 自己的安装程序被它拦住了。
怎么办： 让主机商（或开发人员）把数据库设置 log_bin_trust_function_creators 设为开启（1），然后重新执行 bin/magento setup:upgrade。

2. 命令里出现 `generated/code/Magento cannot be deleted`

原因： Magento 清理缓存文件时偶尔会提示这句，对 GetDropFlow 没有影响。
怎么办： 直接再执行一次同一条命令；通过了就继续，不影响后面的步骤。

3. 整个商店突然打不开：404、"File not found"、"Primary script unknown"、"Permission denied"

原因： 你上传或解压文件之后，商店目录的"所属组"被改掉了，网站程序读不了文件。常见于用主机面板的"文件管理器"上传，或者用 root 解压。
怎么办（交给开发人员/主机商，一句话告诉他）： "请把站点目录的所属用户和组改回网站运行用户，并保证网站程序能读 app/code/DropshipKit。"CloudPanel 面板的做法是 chgrp -R magento-web 站点目录。改完刷新页面确认能打开。
刚用 0.2.21 版升级脚本升级完（首页、登录页、购物车都是 404）？那个脚本把 app/code 的组抄到了 generated、var、pub/static 上；如果网站程序用户只在其中一个组里，就读不了它们。请让每个文件夹回到它原来的组：chgrp -R <原来的组> generated var pub/static（一个文件夹一个文件夹地改），然后刷新。0.2.22 版脚本让每个文件夹保留自己的组（教程 10）。
升级脚本一开始就写着"商店首页在升级前就打不开,所以什么都没有改"(0.2.23 起)?这不是脚本弄坏的:首页在升级之前就已经打不开了,最常见的原因就是上面说的用户组。脚本这时会停下、什么都不改,并打印要用 root 执行的 chgrp -R <WEB_GROUP> . 那一行。修好、确认首页能打开,再重新运行同一条升级命令。
预防： 上传安装包后马上检查权限；用 root 解压后要把 app/code/DropshipKit 的所属用户改回网站用户。

4. 后台里找不到 GetDropFlow 菜单、选品、导入列表

怎么办： 依次确认：① 五个模块都启用了：bin/magento module:status 里能看到 DropshipKit_Catalog、DropshipKit_Orders、DropshipKit_Shipping、DropshipKit_Core、DropshipKit_Admin 且是 enabled；② 执行过 bin/magento setup:upgrade；③ 执行过 bin/magento cache:flush；④ 退出后台重新登录。

5. 商店前台页面样式乱了、商品页或结账页坏了

原因： 静态文件没有为你的店铺实际使用的语言生成。
怎么办： 重新执行 bin/magento setup:static-content:deploy -f 并写上你店铺的所有语言，例如 en_US es_ES zh_Hans_CN，再 bin/magento cache:flush。

6. 升级之后出现奇怪的错误

原因： 手动安装时，没有先删除旧的五个模块文件夹就直接解压覆盖，旧版本里已经不存在的旧文件留了下来。
怎么办： 按第 1 篇的"升级"一节：先备份，删除 app/code/DropshipKit 下的 Admin、Catalog、Core、Orders、Shipping 五个文件夹，再解压新包，然后重新执行 setup:upgrade、编译、静态文件、清缓存。

二、第一次设置的时候

7. 设置页提示"你的授权未生效，这些设置为只读"

怎么办： 打开 GetDropFlow → 设置，在*授权*框里粘贴你的授权码，点 保存 Key 并验证。授权码在官网"我的账户"里查看；如果是免费版，确认这个店铺域名已在账户里领过免费授权码。

8. 点"连接速卖通账号"提示"本店后台地址不是 https"，或"这个商店的地址里没有正规的域名"

原因： 速卖通只能跳回 https:// 开头、带正规域名的地址；localhost 或没有证书的地址不行。
怎么办： 用你商店的正式 https 地址登录后台（地址栏有小锁），再点一次。没有 https 请让主机商开启。

9. 速卖通登录失败、一直要求验证

怎么办： 用你平时的浏览器，不要用被自动化工具控制的窗口；先在另一个标签页登录速卖通，再回后台点"连接速卖通账号"。提示"正在限制请求"就等几分钟再试。

三、日常使用的时候

10. 我发布了商品，但商店里看不到

怎么办： ① 发布后商品是禁用的，要在 Magento 里启用（第 3 篇第 4 步）；② Magento 的 cron（定时任务） 必须在运行，没有 cron，启用了的商品也不会出现在搜索和分类页。请主机商确认 cron 在跑。
刚发布完，商品页显示“缺货”、没有加入购物车按钮： Magento 的库存索引是在后台慢慢生成的，cron 在运行的话几分钟内就会正常。想马上看到，让管理员在服务器上执行 bin/magento indexer:reindex。如果执行后仍是缺货，请告诉我们你的 Magento 版本。

11. 购物车里没有运费

怎么办： 商店 → 配置 → 销售 → 配送方式，打开 GetDropFlow live shipping (AliExpress)，并为你销售的国家填好固定运费表。
第一次加入购物车提示"没有可用的运费"，再试一次就有了：GetDropFlow 向速卖通问运费时最多等 4 秒，不重试；如果这一次没问到（超时、速卖通限流），又没有 24 小时内保存的答复，也没有为这个国家填固定运费，就会没有运费选项。失败的那次什么也不会保存，下一次会重新问，通常就有了。升级之后第一批购物车最容易遇到，因为升级会清缓存。想让第一次也有价钱，请在上面的固定运费表里为你销售的国家填一个固定运费（没有填就是"不提供运费"，这是有意的设计，不会变成免运费）。要查原因：服务器上 var/log/dropshipkit_shipping.log 里找 FALLBACK_TABLE_USED 一行的 reason。

红框：① GetDropFlow live shipping (AliExpress) 这一块；② 启动现在是“否”，要改成“是”；③ 下面的说明文字。

12. 连接速卖通大约两个月后失效

怎么办： GetDropFlow → 设置 → 重新连接（重新授权），这是速卖通授权到期，不是故障。

13. 不知道哪里出了问题

怎么办： 打开 GetDropFlow → 日志，看最近的警告和错误（密钥、地址、邮箱已自动隐藏）。把那一行发给我们，能最快定位。从 0.2.23 起,日志页上方可以按级别(全部 / 只看警告 / 只看错误)和所属部分筛选;时间用商店的时区并写出时区名称(例如 PDT),和设置页的时间一致;"重要操作"表里也有级别一列。
每行后面的数字： 一行说明后面括号里的内容是这条记录带的数字（例如"保存的上一次答复已有 1 小时"），是普通文字，不是代码。
商品数据文件没有被采用： 新文件商品数不到上一份的一半时，日志里会出现"商品数据文件没有被替换……"。同一个原因、同一份旧文件，每 6 小时最多记一次（设置页的审核检查区域始终显示最新一次），所以日志不会被同一行刷满。原因和处理见教程 09。
同一条重复很多次（0.2.23）： 完全相同的记录（同一部分、同一级别、同样的说明和数字）只显示一行，后面写"重复了 N 次；最早一次在……"。后台任务每 10 分钟重新生成一次数据文件，以前同一条"商品数据文件有商品被排除或有缺口"会一次次写进日志，16 小时就把日志的 200 个位置占满，真正的错误会被挤掉。现在这条警告只在原因的种类变了时才写（出现了新原因、某个原因没有了、或开始/不再有商品等运费），原因没变就每天最多写一次；每次写的是"每种原因有多少个商品"，不再列出商品编号。日志页上方显示的条数多了以后，错误会比警告留得更久：超过 200 条时先保留错误，再用警告补满。
原因用文字显示： 例如"图片小于 1000 x 1500（Pinterest）：395"，不再出现 IMAGE_SMALL_FOR_PINTEREST 这样的代码。太长的说明在一个词结束的地方截断（不会截在词中间），把鼠标放在那一行上可以看到完整内容。

红框：① 说明：密钥、令牌、地址、邮箱已隐藏，可以放心截图；② 日志级别 列：WARNING 是警告，ERROR 是错误；③ 例如这一行：授权还没有设置好，缺少授权 Key 或商店地址（对应第 7 条）。

14. 运行 `bin/magento` 时报 `pdo_mysql extension is not installed`

怎么办： 服务器上命令行默认的 php 不是你的 Magento 用的那个版本，缺少数据库扩展。用你的 Magento 对应的 PHP 来运行，例如 php8.4 bin/magento setup:upgrade（Magento 2.4.9 用 8.4，2.4.8 用 8.3 或 8.4，2.4.7 用 8.2 或 8.3，2.4.6 用 8.2）。不确定就问主机商。

15. 安装脚本停下来，提示"GetDropFlow was installed with Composer"或"bin/magento cannot load the shop"

原因： 这个商店以前用 Composer 装过旧版 GetDropFlow（DropshipKit）。它留下的东西（vendor/dropshipkit、composer.lock、composer.json）会和 app/code 里的新版冲突；删掉 Composer 包之后，旧的生成代码和缓存还可能让 bin/magento 报错。
怎么办： 安装脚本没有改动任何东西。请按教程 10里的"以前装过旧版（用 Composer）"做：先备份，composer remove dropshipkit/getdropflow（这一步已经更新了 composer.lock，不要再运行不带包名的 composer update，它会升级你商店里所有的包），删除 generated/code/DropshipKit，清空 var/cache 和 var/page_cache，如果用 Redis/Valkey 就只清本店的缓存库（redis-cli -n <缓存库编号> flushdb，编号在 app/etc/env.php 的 cache 段；不要用 flushall，它会清掉登录会话和同一台服务器上其他网站的数据），再 php bin/magento cache:flush，然后再运行安装脚本。数据库里的表会保留。脚本屏幕上的提示会按你的 env.php 直接写出带正确编号的命令。

16. 安装/升级脚本一开始就停下，提示 "is not allowed to change"（没有权限）

原因： 运行脚本的用户对 app/code、var、generated 或 pub/static（或其中的某些文件）没有写权限，常见原因是以前用 root 运行过命令，留下了归 root 的文件。如果不检查，脚本会在中途删不掉旧文件而停下。
怎么办： 脚本在改动任何东西之前就停了，商店没有受影响。屏幕上会写出命令：chown -R 所有者:组 app/code var generated pub/static。请用 root（或让主机商）运行它，再用店铺文件的所有者重新运行脚本（用 ls -ld app/code 可以看到所有者）。如果升级到一半才出现权限错误，脚本会自动把旧文件放回去；放不完整时会明说，并让商店保持维护模式，按屏幕上的 chown 和 --rollback 命令处理即可。

17. 升级或回退之后，某个语言的后台页面没有样式

原因： production 模式下，静态文件只重新部署了部分语言，少了这个后台用户使用的界面语言（比如 es_ES、zh_Hans_CN）。新版脚本会把商店语言和所有启用的后台用户的界面语言一起部署；用老版脚本或手动步骤时，可能漏掉。
怎么办： 运行 php bin/magento setup:static-content:deploy -f en_US es_ES zh_Hans_CN（换成你需要的全部语言，必须包括后台用户的界面语言），再 php bin/magento cache:flush。

18. 回滚或升级中途停下,商店一直停在维护模式("cannot delete generated/code")

原因: production 模式下,只要有访客打开页面,网站服务器用户(比如 www-data)就会在 generated/code 里生成新文件,商店显示维护页面时也一样。运行脚本的用户删不掉这些文件,于是 rm -rf generated/code 之类的步骤失败。脚本会先检查所有文件夹(包括 generated、var、pub/static 里已经存在的文件),再打开维护模式,然后最多尝试 4 次删除 generated/code(每次间隔 2 秒,并换第二种删法)。在这一步成功之前,脚本绝不会删除旧模块文件夹。
怎么办: 看屏幕上的"已经改变的东西"和"现在的状态"两部分,里面如实写了改变了什么。多数情况下脚本已经自己把商店恢复原状(模块重新启用、维护模式关闭),并会这样说明。如果屏幕说商店仍停在维护模式,请这样做:1)用 root(或请主机商)运行屏幕上给出的 chown 命令,例如 chown -R 所有者:组 app/code var generated pub/static;2)再运行一次同样的命令(例如 bash gdf-install.sh --rollback <备份文件夹>)。脚本会接着上次停下的地方继续,最后打开商店。订单和商品数据不会丢。如果只想先让商店开门:先运行 php bin/magento module:enable DropshipKit_Catalog DropshipKit_Orders DropshipKit_Shipping DropshipKit_Core DropshipKit_Admin,再运行 php bin/magento maintenance:disable(这条命令运行不了时,删除文件 var/.maintenance.flag)。
编译和静态文件会自动重试: 访问量大的店铺里,setup:di:compile(或生成静态文件)运行的同时,网站用户也可能往 generated/ 或 var/ 里写新文件,这一步就会报 "Permission denied"、"Unable to delete" 或 "File exists" 而停下。脚本现在会把这样的步骤最多重做 3 次(屏幕上会看到 "setup:di:compile: try 2 of 3"):每次开始前再检查一遍有没有它改不了的文件,稍等片刻后重新清空 generated/code 和 generated/metadata,再重新运行这一步(编译可以放心重做)。setup:upgrade、module:enable、module:disable 也同样最多重试 3 次。如果 3 次之后仍然停下: 红色的 STOP 行会写出真正的原因(bin/magento 输出的那一行)和准确的 chown 命令。请用 root(或请主机商)运行这条 chown,然后再运行一次同样的命令。屏幕上关于商店的说明是如实的:升级时旧文件会自动还原并重新生成,然后开放商店;如果这次重新生成也失败,以及回滚失败时,商店会特意继续停在维护模式(代码编译不完整或没有样式的店铺,对买家比维护页面更糟)。屏幕上会给出 chown、需要再运行的同一条命令,以及手动开放商店的 php bin/magento maintenance:disable;手动开放意味着店铺会很慢,部分页面可能没有样式,直到同一条命令成功运行为止。只有重建真正完成,脚本才会自己开放商店。可选(需要 root,脚本绝不会自己执行):如果很忙的店铺总是遇到这种情况,可以先停掉 PHP-FPM(例如 systemctl stop php8.3-fpm,这段时间访客看到的是普通的 502 页面),运行同样的命令,结束后再启动(systemctl start php8.3-fpm)。
上一次中途停下的运行留下的维护模式(P20)。 脚本自己打开维护模式、又在它还开着时停下,会写一个小标记文件 var/.gdf-installer-maintenance(时间、命令、版本)。你运行 chown 并再运行一次同样的命令后,脚本会发现这个标记(不超过 24 小时),提示"维护模式是上一次运行停下时留下的",并在成功结束时把维护模式关闭,再删除标记。如果维护模式在没有这种标记的情况下已经打开(你自己打开的,或标记超过 24 小时),脚本照旧保持打开,并说明这一点。

19. 购物车里的小图是母商品的图片（比如红色的裙子），不是我选的颜色

原因： 这是 Magento 自己的设置，不是 GetDropFlow 的问题。可配置商品（颜色 × 尺码）在购物车里默认显示母商品的缩略图。GetDropFlow 不改这个默认值。
怎么办：

1. 后台左侧 商店（Stores）→ 设置（Settings）→ 配置（Configuration）。 2. 左边找到 销售（Sales）→ 结账（Checkout）。 3. 展开 购物车（Shopping Cart），找到 可配置商品图片（Configurable Product Image）（如果显示“使用默认值”，先取消勾选）。 4. 选 商品缩略图本身（Product Thumbnail Itself），不要选 母商品缩略图（Parent Product Thumbnail）。 5. 点 保存配置，再到 系统 → 缓存管理 刷新缓存，然后重新加入一次购物车看看。

注意： 选“商品缩略图本身”后，购物车显示的是所选颜色那个子商品自己的缩略图；如果某个颜色的子商品没有自己的图片，Magento 仍会显示母商品的图片。选项名称按 Magento 后台英文界面写出，中文界面的译文可能略有不同（本条在真实商店里尚未核对）。

20. 日志里有一条“价格和库存同步”被跳过

日志写着“自动同步价格和库存的某一轮被跳过了：GetDropFlow 的文件正在被替换”。当时正在升级：维护模式不会停掉 Magento 的定时任务，所以有一轮碰上了文件替换到一半。不需要做任何事：几分钟后下一轮会自动运行。（0.2.22 之前同样的情况会记成一条错误，内容像“Class ... SyncResult not found”，意思是一样的。）如果没有在升级却反复出现，请告诉我们。

21. 选品搜索写着“搜索失败”，或者找出来的商品和关键词对不上

“搜索失败。速卖通没有返回这些词的结果，也没有给出原因。”速卖通对这次搜索回了“未知错误”（同样的词过一分钟可能就行，换别的词也行）。请等一分钟再搜，或换词。如果每次都失败，请打开日志，把“选品搜索失败”那一行写的内容告诉我们。结果对不上（保险丝、二极管……）：你输入的是中文词。这个速卖通搜索按英文词工作，请改用英文词再搜，例如 summer dress。（在测试店实测：summer dress 有 51217 条相关结果；同一件东西的中文词有 12669 条，前面是保险丝和二极管。速卖通有没有能让中文生效的设置还不知道（未验证）；搜索发出去的语言固定是 en_US。）

22. 结账时只有“Free Shipping $0.00”，没有“Standard shipping”

“Free Shipping - Free”不是 GetDropFlow 的运输方式，是 Magento 自带的“免运费”运输方式。GetDropFlow 自己只有两种情况会显示 $0.00：你设了免运费门槛，或速卖通自己说免运费；这时那一行的名字和 GetDropFlow 的其他方式一样（“Standard shipping ……”）。另外，只要 GetDropFlow 的运费是开启的、并且“隐藏其他运输方式”也是开启的，购物车里有 GetDropFlow 商品时，GetDropFlow 会把其他方式（免运费、固定运费、运费表）全部藏起来。所以如果你只看到 Free Shipping，说明下面三项里有一项成立：GetDropFlow 运费没开、“隐藏其他运输方式”没开、或购物车没被认成 GetDropFlow 的购物车。请到 商店 → 配置 → 销售 → 配送方式，检查 GetDropFlow live shipping (AliExpress) → Enabled 是 Yes、Hide the store's other shipping methods for GetDropFlow products 是 Yes，以及 免运费（Free Shipping） 是 No（出现这个现象的店里这一项是开的，显示“Standard shipping $2.39”的店里不是；到底是三项里的哪一项还没有验证，未验证）。然后清缓存，用新的购物车再试。

23. 商品页和搜索列表显示旧价，但购物车收的是新价

原因：Magento 把商品页存在缓存文件里。改价之后，旧页面有时清不掉：缓存的"标签索引"在并发写入时会丢记录，bin/magento cache:flush 就找不到那些旧文件（有的缓存文件有效期长达 30 天）。怎么办：在 Magento 根目录，用网站的用户运行 php bin/magento cache:flush；如果前台价格还是旧的，再清空 var/cache 和 var/page_cache 两个目录里的文件（只删里面的文件，不删目录本身），然后重新打开页面。0.2.24 起，插件改价后会自己删除对应商品的旧缓存文件。（截图待补）

24. 新导入的商品页能打开，但分类和搜索里找不到

原因：Magento 的"分类关联、价格、库存、搜索"索引偶尔漏掉刚发布的商品。有的商品还会缺价格索引的行。怎么办：运行 php bin/magento indexer:reindex catalog_product_price cataloginventory_stock catalog_category_product catalogsearch_fulltext，再运行 php bin/magento cache:flush。几分钟内完成，不改商品和价格。库存全部为 0 的商品前台本来就隐藏，不是故障。（截图待补）

25. 订单邮件发件人显示 example.com，或客人收不到订单邮件

检查顺序：① 商店 → 配置 → 销售 → 销售邮件和商店邮件地址里的发件人是不是你自己的域名邮箱；② 服务器能不能发信：如果你用 Google Workspace，要在 Google 管理后台的"SMTP 中继服务"里允许你服务器的 IP，并让服务器的邮件程序（如 postfix）经它转发，握手名用你的域名，信封发件人固定为你的客服邮箱；③ 看邮件日志里有没有 "bounced" 和原因。只改后台的 SMTP 用户名密码不是必须的，Magento 用"Sendmail"方式即可。

26. Magento 后台的 SMTP 用户名和密码被浏览器自动填成了你的邮箱账号

Chrome 等浏览器会把保存过的邮箱密码自动填进设置页，保存后会把它存进商店配置。怎么办：把 邮件（SMTP）设置里的用户名和密码清空再保存；到浏览器的"密码管理"里删掉保存的这个网址的密码；如果密码已经出现在配置里，建议改掉这个邮箱的密码。

27. 升级或热修时编译失败，提示 "Directory not empty"

网站在运行时生成过的文件挡住了编译。怎么办：用 root 先清空 generated/code/* 和 generated/metadata/*，再运行 setup:di:compile，最后清缓存并关闭维护模式。官方升级和热修脚本从 v2 起已经包含这一步，失败时会自动还原。

28. Pinterest 或 Google 商品目录里出现很多错误

先看诊断页的错误代码，不要凭感觉改。我们遇到过的：Pinterest 错误 1008（平台说"遇到技术难题"）和警告 1306（附加图下载被限速 429）；Google 的"成人内容""身份和信仰"类提示，常常来自标题里的 sheer、see through、nude、十字架等词。怎么查：先确认商品页和图片能正常打开，再看服务器的网站日志有没有 429（网站日志在 CloudPanel 站点的 logs/nginx-production/access.log；图片和静态文件按设计不记日志）。怎么办：平台自己的错误等下一次接入再看数量；标题有风险词的改标题或下架；附加图太多可以减少。

29. 日志在哪里

CloudPanel 的站点日志在 /home/<站点用户>/logs/nginx-production/access.log 和 error.log。服务器主机名站点另有一个 logs/nginx/，里面几乎是空的，不要看错。看日志前先在 nginx 配置里确认 access_log 指向哪里。

求助时请告诉我们

你做到第几步、点了什么；2. 屏幕上那句红字报错（原文或截图）；3. Magento 版本、PHP 版本（php -v）、主机商或面板名称；4. 日志页里最近几行。

联系我们

[email protected]

中文由 AI 起草，待母语审校。本页会随客人遇到的新问题持续补充。

被 Google 购物中心拒绝或封号

见第 15 篇末尾的"被拒绝或被封号了怎么办"。