前阵子我在一个信创系统环境里处理WordPress粘贴图片转存问题后台从剪贴板贴一张截图转存经常失败。普通电脑上好好的操作一到国产操作系统加国产浏览器的组合就各种报错有的粘贴后显示“HTTP错误”有的图片在编辑器里能看见发布后却变成白屏或者一张断链图。折腾了两天才把链路摸清楚。这篇文章我把这次排查和修复的完整过程写出来给同样要在信创环境部署WordPress的人一个可复现的参考。先说明一下我遇到的环境服务器是Linux系的国产化系统PHP 7.4 Nginx客户端是麒麟/UOS加基于Chromium内核的国产浏览器另外还有一批人习惯用Firefox ESR。WordPress版本6.x后台同时启用了古腾堡和经典编辑器插件。看起来组合不复杂但“粘贴图片转存”这个动作在信创环境里明显比普通Windows Chrome脆弱得多。1. 先看懂“粘贴图片转存”在WordPress里到底怎么工作1.1 浏览器做了什么事WordPress又做了什么很多人以为粘贴图片就是“复制一份图片到服务器”其实不是。当你从系统剪贴板复制一张截图浏览器会从clipboardData里读取一个File对象这个对象在内存里只是一个二进制流并没有实际文件路径。古腾堡编辑器拿到这个File后会先用URL.createObjectURL(file)生成一个blob:临时地址让图片先显示出来同时把File对象交给媒体上传逻辑通过异步请求传到服务器。服务器端接住这个请求的入口是wp-admin/async-upload.php或者新版里的REST接口。WordPress拿到文件后先做扩展名和MIME类型检查再写入wp-content/uploads目录生成附件记录最后把新的图片地址返回给前端。前端拿到真实地址后再把编辑器里那个blob:临时地址替换掉。这个流程里任何一环断了都会表现为“转存失败”。而信创环境最典型的特征就是浏览器兼容层、PHP扩展、服务器默认配置、安全策略都可能和普通环境不一样于是断点会出现在各个意想不到的地方。1.2 信创环境最常见的三种故障现场我在实际接到的反馈里最典型的有三种情况第一种是粘贴后编辑器一直转圈最后弹一个“HTTP错误”。这个错误信息非常模糊它不一定是后端返回的错误可能是上传请求根本没发出去也可能是发出去之后被Nginx或者安全插件拦了。第二种是图片在编辑器里能看到发布后却在文章页面变成空白或者断链。这种情况九成是编辑器把blob:地址直接保存到数据库里了页面刷新后blob:失效图自然就没了。第三种是媒体库里有这张图但是缩略图不生成列表里显示一个碎图标。这通常是服务端的GD库或者Imagick缺了对应图片格式的支持比如WebP、BMP。这三种现象背后其实是不同的问题必须分开排查不能只靠一个插件就想全解。2. 根因排查为什么国产浏览器和信创服务器上转存会断2.1 浏览器侧File.type为空、clipboardData安全限制、自签名证书先从客户端开始查。现在信创办公用的浏览器无非两类一类是基于Chromium内核的国产厂商定制浏览器另一类是Firefox ESR。Chromium内核的浏览器在标准兼容性上和Chrome没有本质区别WordPress默认的粘贴上传逻辑基本能跑。但有个细节容易被忽略这类浏览器在读取系统剪贴板时如果页面权限设置比较严格clipboardData.items可能拿不到文件或者拿到的File.type是空字符串。我遇到过一台麒麟系统上的定制浏览器从系统截图工具复制图片后WordPress收到的文件类型是application/octet-stream而不是image/png。WordPress的wp_check_filetype_and_ext检查到这个类型不匹配直接拒绝了上传。普通用户看到的就是“HTTP错误”完全不理解发生了什么。Firefox ESR这边的问题更隐蔽。Firefox对clipboardData的暴露范围跟Chromium不一样尤其是通过右键菜单“粘贴图片”这种操作JavaScrip很多时候根本拿不到文件对象。这种情况下Gutenberg不会触发上传只会把剪贴板里可能存在的HTML片段插入编辑器图片变成一个外链或者什么也没有。另外还有一个经常被忽视的点如果WordPress后台地址用的是自签名证书或者混合内容浏览器会对跨域请求、异步上传做更严格的限制。信创环境里内网部署很常见很多人图省事用HTTP或者自签HTTPS访问后台这时候粘贴上传请求被浏览器安全策略中断的概率会明显上升。建议把WordPress地址和站点地址都配置成HTTPS并且安装受信任的CA证书至少保证后台页面和上传接口是同源且证书可信的。2.2 服务器侧PHP上传参数、Nginx夹包body限流还有GD库不支持WebP客户端的问题查完之后再看服务器。信创服务器的系统初始化通常比较保守PHP默认配置里upload_max_filesize往往只有2Mpost_max_size只有8M。现在一张截图动辄三四MB还有从网页上直接复制的高清WebP图可能一张就十几MB。超过这个限制后PHP会直接返回一个空响应或者很小的错误页面WordPress的异步上传拿不到正常的JSON于是抛“HTTP错误”。Nginx这边更坑。默认的client_max_body_size是1M意思是只要请求体超过1MNginx在PHP还没看到数据的时候就返回413 Request Entity Too Large。你在后台看到的现象跟PHP上传限制超了几乎一样都是转存失败。很多人在php.ini里把参数调大了Nginx没动照样失败。还有一个特别容易踩的坑是GD库缺少WebP支持。新版WordPress默认允许WebP图片上传但上传之后需要生成缩略图缩略图用的是GD库或者Imagick。如果GD库编译时没有带上WebP模块图片能传上去但缩略图生成失败媒体库里就是一堆坏图。执行php -m | grep -i gd可以确认GD是否加载再用类似php -r var_dump(function_exists(imagewebp));这种方式检查具体函数是否存在。2.3 安全插件和文件权限把上传接口拦在半路安全插件在信创环境里属于双刃剑。Wordfence这类插件默认会扫描上传文件内容还要校验请求里的nonce和登录状态。如果你的WordPress后台有缓存插件、有反向代理的路径改写上传请求携带的参数可能和插件预期的不一致安全插件会直接拦截掉。我见过一台服务器上Wordfence的防火墙规则把async-upload.php的请求当成可疑扫描挡掉了后台粘贴图片就一直报错。文件权限也是个小关卡。WordPress上传目录是wp-content/uploads这个目录需要PHP进程有写权限。信创系统如果是编译安装的Nginx加PHP-FPM进程用户可能是www、nginx或者自定义的而目录属主如果还保留着解压时的root就会出现“无法创建目录”的报错。这句话在wp-content/debug.log里能看到前台表现一样是上传失败。3. 手工兜底用开发者工具从剪贴板把图“抠”出来3.1 在控制台抓取当前页面的Blob URL如果你暂时改不了代码又急着把文章发出去可以用手工方式先顶一下。最直接的办法是在编辑器里粘贴图片后图片还是blob:临时地址的时候打开浏览器的开发者工具在Console里执行一段脚本把所有blob:图片下载下来。[...document.querySelectorAll(img[src^blob:])].forEach((img, i) { fetch(img.src) .then((res) res.blob()) .then((blob) { const a document.createElement(a); a.href URL.createObjectURL(blob); a.download pasted- i .png; a.click(); }); });这段代码会触发浏览器下载每个blob:图片文件名按顺序编号。之后再把下载好的图片上传到WordPress媒体库手动插到文章里。缺点是图片多的时候非常繁琐而且部分浏览器会拦截连续多个自动下载需要用户按一下允许。真碰上紧急情况也可以直接在图片上右键选择在新标签页打开然后CtrlS保存。3.2 对外部链接图片的手工转存还有一类“粘贴图片”其实是粘贴了一段HTML图片地址是外部网站的完整URL。这种情况下编辑器不会下载图片只会把外链存进文章。信创环境的内网访问策略往往对外网做了隔离外链图片可能随时失效发布之后文章里的图就会裂。手工兜底的办法很简单用浏览器打开那个外链图片地址把图片另存到本地然后统一上传到媒体库再回到文章里把src替换成新上传的地址。如果文章量大建议直接用外部图片入库插件或者参考下面第四部分代码做一个自动入库函数。手工方式只适合临时处理一两张图。4. 代码级修复让粘贴图片强制落到媒体库4.1 为什么不用现成插件而是自己写一套WordPress插件库里有很多“自动上传图片”“Paste Image”之类的插件装上之后确实能解决一部分问题。但我在信创项目里不太愿意直接依赖这类第三方插件原因有两个一是它们往往针对古腾堡或者经典编辑器某一端优化兼容性更新跟不上WordPress版本节奏信创浏览器环境下更容易出现兼容问题二是国产化环境的运维审计通常要求后台组件尽量少、尽量可控一个插件引入了额外的前端代码和权限逻辑反而增加排查成本。自己写一套的好处是逻辑清晰从浏览器拿到File对象到服务器返回URL每一步自己都能控制出了问题可以直接看报错日志。下面的方案我按“前端拦截粘贴事件 后端AJAX接收图片 插入编辑器”设计主要针对经典编辑器场景。如果你主力用古腾堡建议只做MIME扩展和服务器参数调整让Gutenberg原生上传链路跑通就够了不要强行拦截。4.2 在functions.php中注册上传处理接口后端部分先加一个AJAX接口接收前端传来的图片文件调用WordPress自带的media_handle_upload写入媒体库。这个函数会处理文件移动、附件记录创建、缩略图生成比手动处理move_uploaded_file省心得多。add_action(wp_ajax_paste_image_upload, paste_image_upload_handler); function paste_image_upload_handler() { check_ajax_referer(paste_image_nonce, nonce); if (!current_user_can(upload_files)) { wp_send_json_error(当前账号没有上传权限); } if (empty($_FILES[image])) { wp_send_json_error(没有接收到图片数据); } require_once ABSPATH . wp-admin/includes/media.php; require_once ABSPATH . wp-admin/includes/file.php; require_once ABSPATH . wp-admin/includes/image.php; $attachment_id media_handle_upload(image, 0); if (is_wp_error($attachment_id)) { wp_send_json_error($attachment_id-get_error_message()); } wp_send_json_success(array( id $attachment_id, url wp_get_attachment_url($attachment_id), )); }这段代码必须放在当前主题的functions.php里或者一个专门的功能插件里。check_ajax_referer是WordPress的nonce验证函数防止有人绕过后台直接提交上传请求。current_user_can(upload_files)则保证只有具备上传权限的人才能调这个接口。4.3 前端JS拦截粘贴事件兼容经典编辑器和BMP转PNG然后在后台文章编辑页加载一段JavaScript。它会在检测到粘贴事件时从剪贴板取出图片文件如果是BMP或者WebP这类兼容性差的格式先通过Canvas转成PNG再交给上传接口。这样做的好处是后端不需要为BMP单独开放MIME白名单缩略图也不会因为格式支持问题而生成失败。(function($) { if (!window.pasteImageVars) return; $(document).on(paste, .wp-editor-area, #content, .block-editor-rich-text__editable, function(e) { var items (e.originalEvent.clipboardData || window.clipboardData || {}).items; if (!items) return; var file null; for (var i 0; i items.length; i) { if (items[i].kind file items[i].type.indexOf(image) 0) { file items[i].getAsFile(); break; } } if (!file) return; e.preventDefault(); if (file.type image/bmp || file.type image/webp) { var img new Image(); img.onload function() { var canvas document.createElement(canvas); canvas.width img.width; canvas.height img.height; canvas.getContext(2d).drawImage(img, 0, 0); canvas.toBlob(function(blob) { uploadImage(blob); }, image/png); }; img.src URL.createObjectURL(file); return; } uploadImage(file); }); function uploadImage(file) { var fd new FormData(); fd.append(action, paste_image_upload); fd.append(nonce, pasteImageVars.nonce); fd.append(image, file, pasted_ Date.now() .png); $.ajax({ url: pasteImageVars.ajaxUrl, type: POST, data: fd, processData: false, contentType: false, dataType: json, success: function(res) { if (res.success res.data.url) { if (window.tinymce) { var editor window.tinymce.get(content) || window.tinymce.activeEditor; if (editor) { editor.insertContent(img src res.data.url classsize-full wp-image- res.data.id /); return; } } var content document.getElementById(content); if (content) { content.value img src res.data.url classsize-full wp-image- res.data.id /; } } else { alert(图片转存失败 (res.data || 未知错误)); } }, error: function(xhr) { alert(图片转存请求异常HTTP xhr.status); } }); } })(jQuery);这段代码在经典编辑器下效果最好。如果你用的是古腾堡e.preventDefault()会打断Gutenberg原生的粘贴上传逻辑所以要注意只有确认自己用经典编辑器时才让这段JS全局生效。更稳妥的做法是在admin_enqueue_scripts里判断当前编辑器的类型或者干脆只在加载classic-editor页面时引入。4.4 顺便处理“粘贴的其实是外部网址”的场景很多时候用户从网页上复制内容粘贴进来的不是截图而是一段带img标签的HTML。WordPress会直接把外部图片地址插入文章并不下载。处理这类情况需要提供一个外部图片入库函数先通过wp_remote_get把图片下载到临时文件再用media_handle_sideload写入媒体库。function paste_image_import_remote($url, $post_id 0) { require_once ABSPATH . wp-admin/includes/media.php; require_once ABSPATH . wp-admin/includes/file.php; require_once ABSPATH . wp-admin/includes/image.php; $tmp wp_tempnam($url); $response wp_remote_get($url, array( timeout 30, stream true, filename $tmp, user-agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/120 Safari/537.36 )); if (is_wp_error($response) || 200 ! (int) wp_remote_retrieve_response_code($response)) { unlink($tmp); return false; } $file_array array( name basename(parse_url($url, PHP_URL_PATH)), tmp_name $tmp ); $attachment_id media_handle_sideload($file_array, $post_id); unlink($tmp); return is_wp_error($attachment_id) ? false : $attachment_id; }注意这里wp_remote_get的stream参数配合filename能把远程文件直接写到临时目录不会一次性占用大量内存。函数返回附件ID你可以把它接到content_save_pre过滤器里扫描文章内容中的外部图片并逐一替换成本地地址。但这样做要小心死循环建议只在首次发布时处理一次并且给每张图片加一个统计标记避免每次保存都重复下载。5. 信创环境的上传通道加固一个参数卡住整条链路5.1 Nginx、PHP、WordPress三者参数必须联动很多转存失败最后查下来不是代码问题而是上传通道的某一层限制设得太小。图片如果超过限制浏览器端拿到的是一个异常响应WordPress根本没见过那个“图片”自然谈不上转存。下面这个表是我项目里固定下来的一套参数建议直接对照改。配置层配置文件参数常见默认值建议取值Nginxnginx.conf 或 conf.d 下的站点配置client_max_body_size1m20mPHPphp.iniupload_max_filesize2M20MPHPphp.inipost_max_size8M25MPHPphp.inimax_execution_time30120PHPphp.inimemory_limit128M256MWordPresswp-config.phpWP_MEMORY_LIMIT40M256Mpost_max_size必须大于upload_max_filesize因为一次POST里除了图片文件还会带上请求头和表单字段。Nginx的client_max_body_size只限制请求体不限制上传文件本身但它限制的是整包所以也必须大于post_max_size。这三个参数任一个小了都会在链路上提前截断请求。改完记得重启Nginx和PHP-FPM不要只reload有些环境reload不会重读client_max_body_size。我遇到过改了配置忘了重启又花了一个小时排查的情况。5.2 上传目录权限、SELinux和AppArmor对写入的约束信创系统底下的SELinux或AppArmor策略往往比普通环境严格。如果你发现WordPress后台提示“无法创建目录”而uploads目录权限明明看起来没问题就要检查系统强制访问控制。排查路径可以这样走先确认PHP-FPM进程用户再确认wp-content/uploads目录属主和权限。常见的组合是PHP-FPM以www-data运行而目录属主也是www-data权限755或775。如果目录属主不对直接执行chown -R www-data:www-data /var/www/html/wp-content/uploads如果权限没问题再看SELinux是否开启。执行getenforce如果返回Enforcing再看看Nginx或PHP相关的布尔值是否允许写文件。类似httpd_can_network_connect、httpd_unified这类布尔值在某些国产化系统里可能默认关闭需要按实际策略放开。AppArmor的情况也类似aa-status可以看到加载的profile如果PHP-FPM的profile限制了站点目录写入需要在对应的profile文件里加上wp-content/uploads的写权限然后重新加载。这一步不同发行版差异很大建议先在测试环境验证别直接上生产机执行。5.3 MIME白名单与信创截图工具格式的坑前面提过BMP和WebP的问题这里展开一下。信创电脑自带的截图工具有的输出PNG有的输出BMP甚至有的输出一种扩展名是.png但实际内容是BMP的畸形文件。WordPress的wp_check_filetype_and_ext会读取文件头来判断真实MIME如果文件名和内容不一致就会直接拒绝。最省心的处理方式是在前端统一转成PNG也就是4.3节那段代码做的事。但如果图片不是通过粘贴进入而是直接在媒体库上传那就得在upload_mimes过滤器里把常见格式加进去add_filter(upload_mimes, function($mimes) { $mimes[png] image/png; $mimes[jpg] image/jpeg; $mimes[jpeg] image/jpeg; $mimes[gif] image/gif; $mimes[webp] image/webp; $mimes[bmp] image/bmp; return $mimes; });但BMP格式即使能上传缩略图也存在风险。如果GD库不支持imagecreatefrombmp媒体库列表会显示异常。所以我的建议是上传和缩略图两头都要控制前端转PNG是最稳的后端只是兜底。6. 回归验证我在麒麟和UOS上的测试记录6.1 测试矩阵设计修复完代码和配置不能只在一台电脑上点一下就说好了。我整理了一个测试矩阵把操作系统、浏览器、编辑器类型三个变量组合起来跑了一遍。实际执行的时候每个组合至少重复三次粘贴上传、一次外部图片地址粘贴、一次大图上传。操作系统浏览器编辑器预期结果麒麟V10国产Chromium内核浏览器古腾堡粘贴PNG/JPG成功BMP自动转PNG成功麒麟V10Firefox ESR经典编辑器用自定义JS接管上传转存成功统信UOS国产Chromium内核浏览器经典编辑器用自定义JS接管上传转存成功统信UOSFirefox ESR古腾堡原生产上传链路成功缩略图正常Windows 10Chrome古腾堡作为基准环境确认无回归实际测试中我发现古腾堡环境最好保持其原生上传逻辑不要用自定义JS去拦截否则可能导致图片插入位置和块结构异常。经典编辑器则适合用4.3节的接管方案体验最稳定。6.2 实测中的两个意外发现第一个意外是Firefox ESR在部分麒麟机器上从系统截图工具复制图片后剪贴板里的文件类型竟然是image/bmp。前端JS判断为BMP后转成PNG问题解决。如果不转WordPress虽然允许BMP上传但缩略图生成失败媒体库显示坏图。这个在我测试环境里复现概率很高建议信创项目统一做格式归一。第二个意外是从网页复制图片时很多浏览器带过来的不是File对象而是一段带外部URL的HTML。这种情况下前端JS拿不到文件只能拿到一个img标签。如果用户复制的内容来自内网其他系统图片地址可能是一个带token的临时URL过几天就失效。后端的paste_image_import_remote函数需要在这时候接手否则文章里的图一定会裂。6.3 发布前必须检查的收尾项上线回归之前我建议你把下面几项逐一确认WordPress后台地址是否走HTTPS证书是否被客户端信任。wp-content/debug.log是否打开过打开后要确认没有反复刷出上传相关错误。Nginx和PHP-FPM是否已经重启参数是否真的生效可以通过上传一张超过2M的图片验证。安全插件的防火墙规则里是否放行了admin-ajax.php和async-upload.php。uploads目录是否设置了合理权限并且SELinux/AppArmor没有阻断写入。用一张BMP截图、一张WebP网页图、一张4M以上的PNG截图分别测试确认前端JS能正确处理。这套流程走下来我在后续几个信创项目里再也没被“粘贴图片转存失败”卡住过。这类兼容问题从来不是单一原因造成的浏览器、PHP、Nginx、GD库、安全插件都可能出一刀把测试矩阵固定下来能省掉大量后期返工。
前阵子我在一个信创系统环境里处理WordPress粘贴图片转存问题后台从剪贴板贴一张截图转存经常失败。普通电脑上好好的操作一到国产操作系统加国产浏览器的组合就各种报错有的粘贴后显示“HTTP错误”有的图片在编辑器里能看见发布后却变成白屏或者一张断链图。折腾了两天才把链路摸清楚。这篇文章我把这次排查和修复的完整过程写出来给同样要在信创环境部署WordPress的人一个可复现的参考。先说明一下我遇到的环境服务器是Linux系的国产化系统PHP 7.4 Nginx客户端是麒麟/UOS加基于Chromium内核的国产浏览器另外还有一批人习惯用Firefox ESR。WordPress版本6.x后台同时启用了古腾堡和经典编辑器插件。看起来组合不复杂但“粘贴图片转存”这个动作在信创环境里明显比普通Windows Chrome脆弱得多。1. 先看懂“粘贴图片转存”在WordPress里到底怎么工作1.1 浏览器做了什么事WordPress又做了什么很多人以为粘贴图片就是“复制一份图片到服务器”其实不是。当你从系统剪贴板复制一张截图浏览器会从clipboardData里读取一个File对象这个对象在内存里只是一个二进制流并没有实际文件路径。古腾堡编辑器拿到这个File后会先用URL.createObjectURL(file)生成一个blob:临时地址让图片先显示出来同时把File对象交给媒体上传逻辑通过异步请求传到服务器。服务器端接住这个请求的入口是wp-admin/async-upload.php或者新版里的REST接口。WordPress拿到文件后先做扩展名和MIME类型检查再写入wp-content/uploads目录生成附件记录最后把新的图片地址返回给前端。前端拿到真实地址后再把编辑器里那个blob:临时地址替换掉。这个流程里任何一环断了都会表现为“转存失败”。而信创环境最典型的特征就是浏览器兼容层、PHP扩展、服务器默认配置、安全策略都可能和普通环境不一样于是断点会出现在各个意想不到的地方。1.2 信创环境最常见的三种故障现场我在实际接到的反馈里最典型的有三种情况第一种是粘贴后编辑器一直转圈最后弹一个“HTTP错误”。这个错误信息非常模糊它不一定是后端返回的错误可能是上传请求根本没发出去也可能是发出去之后被Nginx或者安全插件拦了。第二种是图片在编辑器里能看到发布后却在文章页面变成空白或者断链。这种情况九成是编辑器把blob:地址直接保存到数据库里了页面刷新后blob:失效图自然就没了。第三种是媒体库里有这张图但是缩略图不生成列表里显示一个碎图标。这通常是服务端的GD库或者Imagick缺了对应图片格式的支持比如WebP、BMP。这三种现象背后其实是不同的问题必须分开排查不能只靠一个插件就想全解。2. 根因排查为什么国产浏览器和信创服务器上转存会断2.1 浏览器侧File.type为空、clipboardData安全限制、自签名证书先从客户端开始查。现在信创办公用的浏览器无非两类一类是基于Chromium内核的国产厂商定制浏览器另一类是Firefox ESR。Chromium内核的浏览器在标准兼容性上和Chrome没有本质区别WordPress默认的粘贴上传逻辑基本能跑。但有个细节容易被忽略这类浏览器在读取系统剪贴板时如果页面权限设置比较严格clipboardData.items可能拿不到文件或者拿到的File.type是空字符串。我遇到过一台麒麟系统上的定制浏览器从系统截图工具复制图片后WordPress收到的文件类型是application/octet-stream而不是image/png。WordPress的wp_check_filetype_and_ext检查到这个类型不匹配直接拒绝了上传。普通用户看到的就是“HTTP错误”完全不理解发生了什么。Firefox ESR这边的问题更隐蔽。Firefox对clipboardData的暴露范围跟Chromium不一样尤其是通过右键菜单“粘贴图片”这种操作JavaScrip很多时候根本拿不到文件对象。这种情况下Gutenberg不会触发上传只会把剪贴板里可能存在的HTML片段插入编辑器图片变成一个外链或者什么也没有。另外还有一个经常被忽视的点如果WordPress后台地址用的是自签名证书或者混合内容浏览器会对跨域请求、异步上传做更严格的限制。信创环境里内网部署很常见很多人图省事用HTTP或者自签HTTPS访问后台这时候粘贴上传请求被浏览器安全策略中断的概率会明显上升。建议把WordPress地址和站点地址都配置成HTTPS并且安装受信任的CA证书至少保证后台页面和上传接口是同源且证书可信的。2.2 服务器侧PHP上传参数、Nginx夹包body限流还有GD库不支持WebP客户端的问题查完之后再看服务器。信创服务器的系统初始化通常比较保守PHP默认配置里upload_max_filesize往往只有2Mpost_max_size只有8M。现在一张截图动辄三四MB还有从网页上直接复制的高清WebP图可能一张就十几MB。超过这个限制后PHP会直接返回一个空响应或者很小的错误页面WordPress的异步上传拿不到正常的JSON于是抛“HTTP错误”。Nginx这边更坑。默认的client_max_body_size是1M意思是只要请求体超过1MNginx在PHP还没看到数据的时候就返回413 Request Entity Too Large。你在后台看到的现象跟PHP上传限制超了几乎一样都是转存失败。很多人在php.ini里把参数调大了Nginx没动照样失败。还有一个特别容易踩的坑是GD库缺少WebP支持。新版WordPress默认允许WebP图片上传但上传之后需要生成缩略图缩略图用的是GD库或者Imagick。如果GD库编译时没有带上WebP模块图片能传上去但缩略图生成失败媒体库里就是一堆坏图。执行php -m | grep -i gd可以确认GD是否加载再用类似php -r var_dump(function_exists(imagewebp));这种方式检查具体函数是否存在。2.3 安全插件和文件权限把上传接口拦在半路安全插件在信创环境里属于双刃剑。Wordfence这类插件默认会扫描上传文件内容还要校验请求里的nonce和登录状态。如果你的WordPress后台有缓存插件、有反向代理的路径改写上传请求携带的参数可能和插件预期的不一致安全插件会直接拦截掉。我见过一台服务器上Wordfence的防火墙规则把async-upload.php的请求当成可疑扫描挡掉了后台粘贴图片就一直报错。文件权限也是个小关卡。WordPress上传目录是wp-content/uploads这个目录需要PHP进程有写权限。信创系统如果是编译安装的Nginx加PHP-FPM进程用户可能是www、nginx或者自定义的而目录属主如果还保留着解压时的root就会出现“无法创建目录”的报错。这句话在wp-content/debug.log里能看到前台表现一样是上传失败。3. 手工兜底用开发者工具从剪贴板把图“抠”出来3.1 在控制台抓取当前页面的Blob URL如果你暂时改不了代码又急着把文章发出去可以用手工方式先顶一下。最直接的办法是在编辑器里粘贴图片后图片还是blob:临时地址的时候打开浏览器的开发者工具在Console里执行一段脚本把所有blob:图片下载下来。[...document.querySelectorAll(img[src^blob:])].forEach((img, i) { fetch(img.src) .then((res) res.blob()) .then((blob) { const a document.createElement(a); a.href URL.createObjectURL(blob); a.download pasted- i .png; a.click(); }); });这段代码会触发浏览器下载每个blob:图片文件名按顺序编号。之后再把下载好的图片上传到WordPress媒体库手动插到文章里。缺点是图片多的时候非常繁琐而且部分浏览器会拦截连续多个自动下载需要用户按一下允许。真碰上紧急情况也可以直接在图片上右键选择在新标签页打开然后CtrlS保存。3.2 对外部链接图片的手工转存还有一类“粘贴图片”其实是粘贴了一段HTML图片地址是外部网站的完整URL。这种情况下编辑器不会下载图片只会把外链存进文章。信创环境的内网访问策略往往对外网做了隔离外链图片可能随时失效发布之后文章里的图就会裂。手工兜底的办法很简单用浏览器打开那个外链图片地址把图片另存到本地然后统一上传到媒体库再回到文章里把src替换成新上传的地址。如果文章量大建议直接用外部图片入库插件或者参考下面第四部分代码做一个自动入库函数。手工方式只适合临时处理一两张图。4. 代码级修复让粘贴图片强制落到媒体库4.1 为什么不用现成插件而是自己写一套WordPress插件库里有很多“自动上传图片”“Paste Image”之类的插件装上之后确实能解决一部分问题。但我在信创项目里不太愿意直接依赖这类第三方插件原因有两个一是它们往往针对古腾堡或者经典编辑器某一端优化兼容性更新跟不上WordPress版本节奏信创浏览器环境下更容易出现兼容问题二是国产化环境的运维审计通常要求后台组件尽量少、尽量可控一个插件引入了额外的前端代码和权限逻辑反而增加排查成本。自己写一套的好处是逻辑清晰从浏览器拿到File对象到服务器返回URL每一步自己都能控制出了问题可以直接看报错日志。下面的方案我按“前端拦截粘贴事件 后端AJAX接收图片 插入编辑器”设计主要针对经典编辑器场景。如果你主力用古腾堡建议只做MIME扩展和服务器参数调整让Gutenberg原生上传链路跑通就够了不要强行拦截。4.2 在functions.php中注册上传处理接口后端部分先加一个AJAX接口接收前端传来的图片文件调用WordPress自带的media_handle_upload写入媒体库。这个函数会处理文件移动、附件记录创建、缩略图生成比手动处理move_uploaded_file省心得多。add_action(wp_ajax_paste_image_upload, paste_image_upload_handler); function paste_image_upload_handler() { check_ajax_referer(paste_image_nonce, nonce); if (!current_user_can(upload_files)) { wp_send_json_error(当前账号没有上传权限); } if (empty($_FILES[image])) { wp_send_json_error(没有接收到图片数据); } require_once ABSPATH . wp-admin/includes/media.php; require_once ABSPATH . wp-admin/includes/file.php; require_once ABSPATH . wp-admin/includes/image.php; $attachment_id media_handle_upload(image, 0); if (is_wp_error($attachment_id)) { wp_send_json_error($attachment_id-get_error_message()); } wp_send_json_success(array( id $attachment_id, url wp_get_attachment_url($attachment_id), )); }这段代码必须放在当前主题的functions.php里或者一个专门的功能插件里。check_ajax_referer是WordPress的nonce验证函数防止有人绕过后台直接提交上传请求。current_user_can(upload_files)则保证只有具备上传权限的人才能调这个接口。4.3 前端JS拦截粘贴事件兼容经典编辑器和BMP转PNG然后在后台文章编辑页加载一段JavaScript。它会在检测到粘贴事件时从剪贴板取出图片文件如果是BMP或者WebP这类兼容性差的格式先通过Canvas转成PNG再交给上传接口。这样做的好处是后端不需要为BMP单独开放MIME白名单缩略图也不会因为格式支持问题而生成失败。(function($) { if (!window.pasteImageVars) return; $(document).on(paste, .wp-editor-area, #content, .block-editor-rich-text__editable, function(e) { var items (e.originalEvent.clipboardData || window.clipboardData || {}).items; if (!items) return; var file null; for (var i 0; i items.length; i) { if (items[i].kind file items[i].type.indexOf(image) 0) { file items[i].getAsFile(); break; } } if (!file) return; e.preventDefault(); if (file.type image/bmp || file.type image/webp) { var img new Image(); img.onload function() { var canvas document.createElement(canvas); canvas.width img.width; canvas.height img.height; canvas.getContext(2d).drawImage(img, 0, 0); canvas.toBlob(function(blob) { uploadImage(blob); }, image/png); }; img.src URL.createObjectURL(file); return; } uploadImage(file); }); function uploadImage(file) { var fd new FormData(); fd.append(action, paste_image_upload); fd.append(nonce, pasteImageVars.nonce); fd.append(image, file, pasted_ Date.now() .png); $.ajax({ url: pasteImageVars.ajaxUrl, type: POST, data: fd, processData: false, contentType: false, dataType: json, success: function(res) { if (res.success res.data.url) { if (window.tinymce) { var editor window.tinymce.get(content) || window.tinymce.activeEditor; if (editor) { editor.insertContent(img src res.data.url classsize-full wp-image- res.data.id /); return; } } var content document.getElementById(content); if (content) { content.value img src res.data.url classsize-full wp-image- res.data.id /; } } else { alert(图片转存失败 (res.data || 未知错误)); } }, error: function(xhr) { alert(图片转存请求异常HTTP xhr.status); } }); } })(jQuery);这段代码在经典编辑器下效果最好。如果你用的是古腾堡e.preventDefault()会打断Gutenberg原生的粘贴上传逻辑所以要注意只有确认自己用经典编辑器时才让这段JS全局生效。更稳妥的做法是在admin_enqueue_scripts里判断当前编辑器的类型或者干脆只在加载classic-editor页面时引入。4.4 顺便处理“粘贴的其实是外部网址”的场景很多时候用户从网页上复制内容粘贴进来的不是截图而是一段带img标签的HTML。WordPress会直接把外部图片地址插入文章并不下载。处理这类情况需要提供一个外部图片入库函数先通过wp_remote_get把图片下载到临时文件再用media_handle_sideload写入媒体库。function paste_image_import_remote($url, $post_id 0) { require_once ABSPATH . wp-admin/includes/media.php; require_once ABSPATH . wp-admin/includes/file.php; require_once ABSPATH . wp-admin/includes/image.php; $tmp wp_tempnam($url); $response wp_remote_get($url, array( timeout 30, stream true, filename $tmp, user-agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/120 Safari/537.36 )); if (is_wp_error($response) || 200 ! (int) wp_remote_retrieve_response_code($response)) { unlink($tmp); return false; } $file_array array( name basename(parse_url($url, PHP_URL_PATH)), tmp_name $tmp ); $attachment_id media_handle_sideload($file_array, $post_id); unlink($tmp); return is_wp_error($attachment_id) ? false : $attachment_id; }注意这里wp_remote_get的stream参数配合filename能把远程文件直接写到临时目录不会一次性占用大量内存。函数返回附件ID你可以把它接到content_save_pre过滤器里扫描文章内容中的外部图片并逐一替换成本地地址。但这样做要小心死循环建议只在首次发布时处理一次并且给每张图片加一个统计标记避免每次保存都重复下载。5. 信创环境的上传通道加固一个参数卡住整条链路5.1 Nginx、PHP、WordPress三者参数必须联动很多转存失败最后查下来不是代码问题而是上传通道的某一层限制设得太小。图片如果超过限制浏览器端拿到的是一个异常响应WordPress根本没见过那个“图片”自然谈不上转存。下面这个表是我项目里固定下来的一套参数建议直接对照改。配置层配置文件参数常见默认值建议取值Nginxnginx.conf 或 conf.d 下的站点配置client_max_body_size1m20mPHPphp.iniupload_max_filesize2M20MPHPphp.inipost_max_size8M25MPHPphp.inimax_execution_time30120PHPphp.inimemory_limit128M256MWordPresswp-config.phpWP_MEMORY_LIMIT40M256Mpost_max_size必须大于upload_max_filesize因为一次POST里除了图片文件还会带上请求头和表单字段。Nginx的client_max_body_size只限制请求体不限制上传文件本身但它限制的是整包所以也必须大于post_max_size。这三个参数任一个小了都会在链路上提前截断请求。改完记得重启Nginx和PHP-FPM不要只reload有些环境reload不会重读client_max_body_size。我遇到过改了配置忘了重启又花了一个小时排查的情况。5.2 上传目录权限、SELinux和AppArmor对写入的约束信创系统底下的SELinux或AppArmor策略往往比普通环境严格。如果你发现WordPress后台提示“无法创建目录”而uploads目录权限明明看起来没问题就要检查系统强制访问控制。排查路径可以这样走先确认PHP-FPM进程用户再确认wp-content/uploads目录属主和权限。常见的组合是PHP-FPM以www-data运行而目录属主也是www-data权限755或775。如果目录属主不对直接执行chown -R www-data:www-data /var/www/html/wp-content/uploads如果权限没问题再看SELinux是否开启。执行getenforce如果返回Enforcing再看看Nginx或PHP相关的布尔值是否允许写文件。类似httpd_can_network_connect、httpd_unified这类布尔值在某些国产化系统里可能默认关闭需要按实际策略放开。AppArmor的情况也类似aa-status可以看到加载的profile如果PHP-FPM的profile限制了站点目录写入需要在对应的profile文件里加上wp-content/uploads的写权限然后重新加载。这一步不同发行版差异很大建议先在测试环境验证别直接上生产机执行。5.3 MIME白名单与信创截图工具格式的坑前面提过BMP和WebP的问题这里展开一下。信创电脑自带的截图工具有的输出PNG有的输出BMP甚至有的输出一种扩展名是.png但实际内容是BMP的畸形文件。WordPress的wp_check_filetype_and_ext会读取文件头来判断真实MIME如果文件名和内容不一致就会直接拒绝。最省心的处理方式是在前端统一转成PNG也就是4.3节那段代码做的事。但如果图片不是通过粘贴进入而是直接在媒体库上传那就得在upload_mimes过滤器里把常见格式加进去add_filter(upload_mimes, function($mimes) { $mimes[png] image/png; $mimes[jpg] image/jpeg; $mimes[jpeg] image/jpeg; $mimes[gif] image/gif; $mimes[webp] image/webp; $mimes[bmp] image/bmp; return $mimes; });但BMP格式即使能上传缩略图也存在风险。如果GD库不支持imagecreatefrombmp媒体库列表会显示异常。所以我的建议是上传和缩略图两头都要控制前端转PNG是最稳的后端只是兜底。6. 回归验证我在麒麟和UOS上的测试记录6.1 测试矩阵设计修复完代码和配置不能只在一台电脑上点一下就说好了。我整理了一个测试矩阵把操作系统、浏览器、编辑器类型三个变量组合起来跑了一遍。实际执行的时候每个组合至少重复三次粘贴上传、一次外部图片地址粘贴、一次大图上传。操作系统浏览器编辑器预期结果麒麟V10国产Chromium内核浏览器古腾堡粘贴PNG/JPG成功BMP自动转PNG成功麒麟V10Firefox ESR经典编辑器用自定义JS接管上传转存成功统信UOS国产Chromium内核浏览器经典编辑器用自定义JS接管上传转存成功统信UOSFirefox ESR古腾堡原生产上传链路成功缩略图正常Windows 10Chrome古腾堡作为基准环境确认无回归实际测试中我发现古腾堡环境最好保持其原生上传逻辑不要用自定义JS去拦截否则可能导致图片插入位置和块结构异常。经典编辑器则适合用4.3节的接管方案体验最稳定。6.2 实测中的两个意外发现第一个意外是Firefox ESR在部分麒麟机器上从系统截图工具复制图片后剪贴板里的文件类型竟然是image/bmp。前端JS判断为BMP后转成PNG问题解决。如果不转WordPress虽然允许BMP上传但缩略图生成失败媒体库显示坏图。这个在我测试环境里复现概率很高建议信创项目统一做格式归一。第二个意外是从网页复制图片时很多浏览器带过来的不是File对象而是一段带外部URL的HTML。这种情况下前端JS拿不到文件只能拿到一个img标签。如果用户复制的内容来自内网其他系统图片地址可能是一个带token的临时URL过几天就失效。后端的paste_image_import_remote函数需要在这时候接手否则文章里的图一定会裂。6.3 发布前必须检查的收尾项上线回归之前我建议你把下面几项逐一确认WordPress后台地址是否走HTTPS证书是否被客户端信任。wp-content/debug.log是否打开过打开后要确认没有反复刷出上传相关错误。Nginx和PHP-FPM是否已经重启参数是否真的生效可以通过上传一张超过2M的图片验证。安全插件的防火墙规则里是否放行了admin-ajax.php和async-upload.php。uploads目录是否设置了合理权限并且SELinux/AppArmor没有阻断写入。用一张BMP截图、一张WebP网页图、一张4M以上的PNG截图分别测试确认前端JS能正确处理。这套流程走下来我在后续几个信创项目里再也没被“粘贴图片转存失败”卡住过。这类兼容问题从来不是单一原因造成的浏览器、PHP、Nginx、GD库、安全插件都可能出一刀把测试矩阵固定下来能省掉大量后期返工。
