简介：Woocommerce 3.5.2 安装包面向使用 WordPress 搭建在线商店的开发者与店主，提供创建和管理电商站点所需的完整插件文件，适合具备一定 WordPress 基础、希望自行部署或研究插件结构的用户。压缩包共 1099 个文件，约 3.73MB，以 814 个 php 核心逻辑文件为主，辅以 142 个 js 交互脚本、36 个 css 与 20 个 scss 样式文件，以及 png、svg、gif 等图像资源和 ttf、woff、eot 字体文件，另含少量 xml、yml、csv、pot 等配置与本地化文件，结构完整便于二次开发与主题适配。该版本在性能优化、WordPress 5.x 兼容性、安全补丁、管理界面与结账流程、支付网关 API、报表统计、物流运费及多语言支持等方面均有改进。目前已有 439 人学习下载，读者可借此研究插件目录组织、前端资源加载与后台模块划分，为店铺部署和功能扩展提供参考。

1. 老版本 WooCommerce 安装包：为什么还有人专门找 3.5.2

上周有个做外贸独立站的朋友半夜找我，说客户要求把商城回滚到 WooCommerce 3.5.2，因为新版本把一套用了三年的自定义结算逻辑搞崩了。这不是个例——在跨境电商和 WordPress 生态里，锁定某个旧版本安装包是常态操作。WooCommerce 3.5.2 发布于 2018 年初，属于 3.x 系列的稳定分支，它最大的特点是短代码体系完整、对老主题兼容性好、数据库表结构简单。很多跑了好几年的站点，主题和插件都是围绕这个版本写的，贸然升级到 4.x 或 8.x，轻则样式错乱，重则订单流程断裂。这篇文章面向的是需要精确复现这个版本环境的开发者、运维和独立站站长，我会把安装包获取、环境搭建、参数配置、常见报错排查整条链路讲清楚，让你在本地或测试服上跑通一个可用的 WooCommerce 3.5.2 环境。

2. 先搞清楚 WooCommerce 3.5.2 的安装包结构和依赖边界

2.1 安装包里到底有什么

WooCommerce 的官方分发形式是一个 WordPress 插件压缩包，命名规则通常是woocommerce.3.5.2.zip。解压之后你会看到一个标准插件目录结构，核心内容大致如下：

这里有个关键点：3.5.2 的模板覆盖机制和后续版本有差异。3.5.x 时代，主题覆盖模板的路径是yourtheme/woocommerce/，这个规则一直没变，但 3.5.2 里部分模板文件（比如cart/cart.php）的钩子位置和 4.x 不同。如果你从新版本降级回来，主题里已经按新钩子改过的模板会直接报错。

2.2 为什么必须锁死 PHP 和 WordPress 版本

WooCommerce 3.5.2 官方声明的兼容范围是 WordPress 4.4 到 4.9，PHP 5.6 到 7.2。这不是随便写的——3.5.2 的代码里用了大量 PHP 7.2 之前才支持的写法，比如没有标量类型声明、没有返回类型声明。如果你把它扔到 PHP 8.0 环境里，第一屏就会看到Deprecated: Required parameter follows optional parameter这类警告，严重时直接白屏。

我一般会这样配环境：

• WordPress：4.9.26（4.9 分支最后一个维护版）
• PHP：7.2.x（7.2 是 3.5.2 能稳定跑的最高版本）
• MySQL：5.7 或 MariaDB 10.2
• Web 服务器：Nginx 或 Apache 都行，关键是 rewrite 规则要配对

提示：不要用 PHP 7.4 及以上版本跑 3.5.2，虽然部分功能能跑，但结算页面的 AJAX 请求会因为implode()参数顺序问题随机失败，这种玄学问题排查起来非常费时间。

2.3 安装包获取的可靠路径

官方仓库的历史版本可以通过 WordPress 插件 SVN 或 GitHub 的 tag 页面获取。常见做法是直接下载woocommerce.3.5.2.zip这个固定命名文件。如果你在服务器上操作，可以用 WP-CLI 指定版本安装：

# 用 WP-CLI 安装指定版本的 WooCommerce wp plugin install woocommerce --version=3.5.2 --activate # 查看当前插件版本确认 wp plugin get woocommerce --field=version # 如果需要强制降级，先删再装 wp plugin delete woocommerce wp plugin install woocommerce --version=3.5.2 --activate

这段命令的逻辑是：WP-CLI 会从官方仓库拉取指定 tag 的压缩包，解压到wp-content/plugins/woocommerce，然后激活。--version参数接受语义化版本号，--activate表示安装后立即启用。注意，如果当前已有更高版本，直接 install 会提示已安装，所以降级场景要先 delete。执行完用wp plugin get确认版本号确实是 3.5.2，避免缓存导致误判。

3. 在本地把 WooCommerce 3.5.2 跑起来的最小步骤

3.1 用 Docker 搭一个隔离环境

手动配 PHP 7.2 + WordPress 4.9 比较折腾，我习惯用 Docker Compose 一次性拉起。下面这个配置是我在多个测试环境里用过的，能稳定跑 3.5.2：

version: '3.7' services: db: image: mysql:5.7 environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: wordpress MYSQL_USER: wpuser MYSQL_PASSWORD: wppass volumes: - db_data:/var/lib/mysql ports: - "3307:3306" wordpress: image: wordpress:4.9.26-php7.2-apache depends_on: - db environment: WORDPRESS_DB_HOST: db:3306 WORDPRESS_DB_USER: wpuser WORDPRESS_DB_PASSWORD: wppass WORDPRESS_DB_NAME: wordpress volumes: - wp_data:/var/www/html ports: - "8080:80" volumes: db_data: wp_data:

这个 compose 文件的关键参数说明：wordpress:4.9.26-php7.2-apache这个镜像标签同时锁定了 WordPress 版本和 PHP 版本，省得自己编译。数据库用 MySQL 5.7，端口映射到 3307 避免和本机已有 MySQL 冲突。wp_data卷保证容器重启后插件和上传文件不丢。启动命令就是docker-compose up -d，等十几秒后访问http://localhost:8080走完 WordPress 安装向导。

3.2 安装 WooCommerce 3.5.2 并跳过向导

WordPress 装好后，进入后台插件页面，上传前面下载的woocommerce.3.5.2.zip，激活。激活后 WooCommerce 会跳出一个设置向导，如果你是在做测试环境，建议直接点“跳过设置”，因为向导会创建一堆示例页面和菜单，反而干扰排查。

跳过向导后，需要手动确认几个核心页面是否绑定正确。进入WooCommerce → 设置 → 高级，检查购物车、结算、我的账户这几个页面的 ID 是否指向已存在的页面。3.5.2 有时候在跳过向导后不会自动创建这些页面，需要手动新建并在下拉框里选中。

// 在主题 functions.php 里临时加一段，检查 WooCommerce 页面绑定情况 add_action('admin_notices', function() { if (!current_user_can('manage_options')) return; $pages = array( 'woocommerce_cart_page_id' => '购物车', 'woocommerce_checkout_page_id' => '结算', 'woocommerce_myaccount_page_id'=> '我的账户', ); foreach ($pages as $option => $label) { $page_id = get_option($option); if (!$page_id || get_post_status($page_id) !== 'publish') { echo '<div class="notice notice-error"><p>' . $label . ' 页面未正确绑定</p></div>'; } } });

这段代码挂在admin_notices钩子上，只在后台显示，用来快速定位页面绑定缺失。get_option读取 WooCommerce 存储的页面 ID，get_post_status确认页面已发布。如果某个页面显示未绑定，就去设置 → 高级里重新选。排查完记得把这段代码删掉，别留在生产环境。

3.3 导入测试数据验证订单流程

环境跑通后，别急着装主题。先用 WooCommerce 自带的示例数据生成器造几个产品，走一遍下单流程。3.5.2 的示例数据生成器在工具 → 示例数据里，但那个生成器有时候会超时。更可靠的方式是用 WP-CLI 批量创建产品：

# 创建几个简单产品用于测试 for i in 1 2 3; do wp wc product create --name="测试产品$i" --type=simple --regular_price="99" --user=admin done # 确认产品已创建 wp wc product list --user=admin --fields=id,name,price

wp wc命令需要 WooCommerce 的 CLI 支持，3.5.2 自带这个功能。--user=admin指定以管理员身份执行，避免权限报错。创建完产品后，前台访问商城页面，加购、进购物车、填结算信息、下单。如果结算页面卡在“正在处理”不动，大概率是 AJAX 请求被主题或插件拦截了，这时候切到默认主题（如 Twenty Seventeen）再试一次，能快速判断是环境问题还是主题冲突。

4. 版本锁定后最容易翻车的几个配置点

4.1 固定链接和 rewrite 规则

WooCommerce 3.5.2 对固定链接很敏感。如果你把固定链接设成“朴素”模式（带?p=123那种），产品分类页和标签页会 404。正确做法是进设置 → 固定链接，选“文章名”或“自定义结构”，保存后 WooCommerce 会自动刷新 rewrite 规则。但有时候自动刷新不生效，需要手动触发：

# 刷新 WordPress rewrite 规则 wp rewrite flush --hard # 如果用的是 Nginx，确认 try_files 配置正确 # 在 nginx.conf 的 server 块里应有： # location / { try_files $uri $uri/ /index.php?$args; }

wp rewrite flush --hard会直接更新.htaccess（Apache）或提示你更新 Nginx 配置。Nginx 环境下没有.htaccess，必须手动在 server 块里加try_files指令，否则产品详情页永远 404。这个坑我踩过不止一次，尤其是从 Apache 迁移到 Nginx 的时候。

4.2 库存和税率表的前缀问题

WooCommerce 3.5.2 创建的自定义表包括wp_woocommerce_order_items、wp_woocommerce_order_itemmeta、wp_woocommerce_tax_rates等。如果你在wp-config.php里改了$table_prefix，这些表的前缀会跟着变，但 3.5.2 的某些查询语句里硬编码了wp_前缀的情况虽然少见，但在税率导入功能里出现过。表现是导入 CSV 税率表时提示表不存在。

解决办法是保持默认的wp_前缀，或者在导入前用 SQL 检查表名：

-- 查看当前所有 WooCommerce 相关表 SHOW TABLES LIKE '%woocommerce%'; -- 如果前缀不是 wp_，确认税率表是否存在 SHOW TABLES LIKE '%woocommerce_tax_rates';

如果表存在但导入报错，大概率是 CSV 格式问题。3.5.2 的税率导入要求 CSV 列顺序为：国家代码、州代码、邮编、城市、税率、税名、优先级、复合税、运费税。列顺序错了不会报错，但数据会错位，这个坑很隐蔽。

4.3 支付网关的回调地址

3.5.2 时代的支付网关插件（比如某些第三方信用卡网关）回调地址通常写的是WC()->api_request_url('gateway_id')。这个函数生成的 URL 依赖 WordPress 的 home URL 和 permalink 结构。如果你在本地测试时用的是localhost:8080，回调地址就是http://localhost:8080/?wc-api=gateway_id。但有些网关插件在 3.5.2 下会把回调地址写成固定路径，导致本地测试永远收不到异步通知。

排查方法是打开网关的调试日志，看它实际请求的 URL 是什么。WooCommerce 3.5.2 的日志在WooCommerce → 状态 → 日志里，选对应的网关日志文件。如果看到 404，就对比WC()->api_request_url生成的地址和网关配置里的地址是否一致。不一致的话，要么改网关配置，要么在wp-config.php里强制设置WP_HOME和WP_SITEURL为可公网访问的域名。

5. 避坑：WooCommerce 3.5.2 降级和运行中的五个血泪教训

5.1 现象：降级后后台白屏，前台正常

原因：新版本 WooCommerce 在数据库里写入了一些 3.5.2 不认识的选项和表字段，降级后插件加载时读取这些数据触发致命错误。常见的是woocommerce_db_version选项值高于 3.5.2 期望的值。

解决：降级前先备份数据库，降级后用 SQL 手动把woocommerce_db_version改回3.5.2，并删除wp_options里以woocommerce_开头但 3.5.2 不认识的选项。更稳妥的做法是全新安装 3.5.2，再导入产品数据。

5.2 现象：结算页面无限加载，控制台报 500

原因：PHP 版本过高导致wc-ajax=checkout请求里某个函数返回类型不匹配。3.5.2 的WC_AJAX::checkout()方法在 PHP 7.4 下会因为implode()参数顺序警告而中断。

解决：把 PHP 降到 7.2，或者在wp-config.php里临时关闭错误显示：ini_set('display_errors', 0);。但关闭显示只是掩盖问题，根本方案还是降 PHP 版本。

5.3 现象：产品图片上传后不显示，媒体库正常

原因：3.5.2 的图片尺寸注册逻辑和后续版本不同，如果主题里用了add_image_size注册了同名尺寸，会覆盖 WooCommerce 的尺寸定义，导致产品图调用的是不存在的缩略图。

解决：进WooCommerce → 设置 → 产品 → 显示，把产品图片尺寸改一个值保存，再改回来，强制重新生成缩略图。或者用wp media regenerate命令重新生成所有图片尺寸。

5.4 现象：优惠券应用后总价不变

原因：3.5.2 的优惠券计算依赖购物车会话，如果服务器开启了页面缓存（比如 Nginx 的 fastcgi_cache），购物车会话可能被缓存，导致优惠券逻辑读到旧数据。

解决：在缓存配置里排除/?wc-ajax=*和/cart/、/checkout/路径，或者给这些页面设置Cache-Control: no-cache。WooCommerce 官方也建议在wp-config.php里定义DONOTCACHEPAGE常量。

5.5 现象：订单邮件收不到，日志显示已发送

原因：3.5.2 默认用wp_mail()发邮件，很多服务器环境没有配 SMTP，PHP mail 函数被禁用或丢件。日志里显示“邮件已发送”只是说wp_mail()没报错，不代表对方收到了。

解决：装一个 SMTP 插件，配置真实的 SMTP 账号。3.5.2 兼容的 SMTP 插件版本也要注意，太新的版本可能用了 4.x 的钩子。我一般用 WP Mail SMTP 的旧版本，或者直接在主题functions.php里用phpmailer_init钩子硬编码 SMTP 配置。

6. 用 WP-CLI 批量校验 3.5.2 环境完整性的一个技巧

环境搭好之后，怎么确认它真的“完整”？我习惯写一个 WP-CLI 命令组合，把关键指标一次性拉出来。这个技巧在给客户交付测试环境时特别有用，能避免“看起来能跑，实际缺东西”的尴尬。

#!/bin/bash # wc352-check.sh - 校验 WooCommerce 3.5.2 环境完整性 echo "=== WordPress 版本 ===" wp core version echo "=== WooCommerce 版本 ===" wp plugin get woocommerce --field=version echo "=== PHP 版本 ===" wp eval 'echo PHP_VERSION;' echo "=== 数据库版本标记 ===" wp option get woocommerce_db_version echo "=== 核心页面绑定 ===" wp eval ' $pages = array("woocommerce_cart_page_id","woocommerce_checkout_page_id","woocommerce_myaccount_page_id","woocommerce_shop_page_id"); foreach ($pages as $p) { $id = get_option($p); echo $p . ": " . ($id ? get_permalink($id) : "未绑定") . "\n"; }' echo "=== 已激活的支付网关 ===" wp eval ' $gateways = WC()->payment_gateways->get_available_payment_gateways(); foreach ($gateways as $id => $gw) { echo $id . " - " . $gw->get_title() . "\n"; }' echo "=== 最近 10 条订单 ===" wp wc order list --user=admin --limit=10 --fields=id,status,total,date_created

这个脚本的核心思路是用wp eval直接执行 PHP 代码片段，绕过 WP-CLI 没有封装的功能。wp option get woocommerce_db_version确认数据库版本标记和插件版本一致，不一致说明降级不彻底。页面绑定检查用get_permalink输出实际 URL，比只看 ID 直观。支付网关列表能快速确认网关插件是否在 3.5.2 下正常注册。最后拉最近订单，确认订单表可读。

跑完这个脚本，如果所有输出都符合预期，说明环境基本可用。如果某个环节报错，错误信息会直接告诉你缺什么。比如wp wc order list报“命令不存在”，说明 WooCommerce 的 CLI 包没加载，需要检查wp-content/plugins/woocommerce/includes/cli/目录是否存在。

我自己的习惯是把这个脚本存成wc352-check.sh，每次新建测试环境后跑一遍，省得手动点后台。这个习惯帮我省下了大量“以为配好了结果漏了页面绑定”的后悔药时间。环境校验这件事，宁可多花两分钟跑脚本，也别等客户测试时才发现问题。希望帮到你。

本文还有配套的精品资源，点击获取