安装指南

跨境电商本地静默打印解决方案

Windows & macOS PDF · HTML · ZPL 检测服务中…
1
下载安装包并解压
从下载中心下载 wandox-print-agent-vX.X.X-windows-x64.zip，右键点击 ZIP 文件 → 全部解压，解压到任意文件夹（例如桌面）。
💡 解压后会得到一个同名文件夹，里面包含 wandox-print-agent.exe、SDK/、examples/ 等文件。
2
双击运行 wandox-print-agent.exe
进入解压后的文件夹，双击 wandox-print-agent.exe 运行程序。
3
处理 Windows 安全提示（首次运行）
首次运行时 Windows 可能弹出蓝色安全提示框，这是 Windows 对未签名程序的正常提示，Wandox 打印助手是安全软件，按以下步骤继续：
🛡
Windows 已保护你的电脑
Microsoft Defender SmartScreen 阻止了无法识别的应用启动
运行此应用可能会使你的电脑面临风险。
👉 第一步：点击「更多信息」
不运行
点击「更多信息」后出现： 👉 第二步：仍然运行
⚠️ 如果没有弹出安全提示，说明 Windows 已信任该程序，可以直接跳到下一步。
✓
在任务栏找到托盘图标 = 运行成功
程序启动后会在屏幕右下角系统托盘（时钟旁边的小图标区域）显示蓝色六边形图标。
如果看不到，点击托盘区域的 「 ∧ 」展开箭头 查找隐藏图标。
任务栏右下角： …
Wandox Print Agent
✅ 右键点击托盘图标可查看服务状态、修改端口、安装证书等选项。
💡 如果你的业务系统是 HTTP 页面，跳过此步骤。只有 HTTPS 页面才需要信任证书。每台电脑只需操作一次。
1
通过托盘菜单安装证书（推荐）
右键点击系统托盘图标 → 点击 「🔒 安装证书到系统」 → 弹出 Windows 安全对话框，点击 「是」 确认。
Chrome、Edge、Safari 将自动信任，无需其他操作。
2
Firefox 用户额外操作
右键托盘 → 点击 「🦊 配置 Firefox 证书信任」 → 重启 Firefox 即可生效。
3
无托盘菜单时：浏览器内手动信任
浏览器访问 https://127.0.0.1:9100 → 点击「高级」→「继续访问 127.0.0.1（不安全）」。
看到「证书已受信」页面即完成，此后同一浏览器不再提示。
1
下载安装包并解压
从下载中心下载 wandox-print-agent-vX.X.X-macos.zip，双击 ZIP 文件自动解压，解压后得到 WandoxPrintAgent.app。
💡 可将 WandoxPrintAgent.app 拖到「应用程序」文件夹，方便后续启动。
2
双击打开 WandoxPrintAgent.app
双击应用图标运行程序。
3
处理 macOS 安全提示（首次运行）
首次运行时 macOS 可能弹出「无法验证开发者」提示，这是 macOS 对非 App Store 程序的正常保护机制，按以下步骤继续：
Wandox
无法打开 "WandoxPrintAgent.app"，因为 Apple 无法检查其是否包含恶意软件。
此软件需要更新。请联系开发者了解更多信息。
好
🔧
解决方法（三步）：
  1. 打开「系统设置」→「隐私与安全性」
  2. 在「安全性」区域找到「已阻止使用 WandoxPrintAgent…」的提示
  3. 点击 「仍然打开」，输入系统密码确认
⚠️ macOS Sequoia (15) 用户：在「隐私与安全性」中如果看不到按钮，尝试在 Finder 中右键点击 .app → 选择「打开」。
✓
在菜单栏找到图标 = 运行成功
程序启动后会在屏幕右上角菜单栏显示蓝色六边形图标。
菜单栏右上角：
Wandox Wi-Fi   🔋   ⊞
✅ 点击菜单栏图标可查看服务状态、修改端口、安装证书等选项。
💡 如果你的业务系统是 HTTP 页面，跳过此步骤。只有 HTTPS 页面才需要信任证书。每台 Mac 只需操作一次。
1
通过托盘菜单安装证书（推荐）
点击菜单栏图标 → 点击 「🔒 安装证书到系统」 → 弹出钥匙串密码框，输入登录密码确认。
Chrome、Edge、Safari 将自动信任，无需其他操作。
2
Firefox 用户额外操作
点击菜单栏图标 → 「🦊 配置 Firefox 证书信任」 → 重启 Firefox 即可生效。
3
无托盘菜单时：浏览器内手动信任
Safari / Chrome 访问 https://127.0.0.1:9100 → 点击「继续」或「高级」→「继续访问」。
看到「证书已受信」页面即完成。
检测服务是否正常运行

一键检测本机打印服务

自动检测各端口状态：9000 为 Wandox 主服务，8000 / 8498 为 Wandox 自身的兼容层端口（用于接管旧 SDK 调用）。

常见问题
  1. 检查任务管理器中是否已有 wandox-print-agent.exe 进程在运行（可能是被杀毒软件静默拦截后重启）。
  2. 部分杀毒软件（如火绒、360）会在后台静默拦截 .exe，请检查杀毒软件的拦截日志，添加白名单。
  3. 确认 EXE 文件没有被放在带中文路径或空格路径下（建议放在 C:\wandox\ 等简单路径）。

Wandox 打印助手是安全软件，但由于程序包含本地网络服务能力，部分杀毒引擎可能误报（误报率与签名厂商有关）。

  • 在杀毒软件中将 wandox-print-agent.exe 所在文件夹加入白名单 / 信任区
  • Windows Defender：打开「病毒和威胁防护」→「排除项」→「添加排除项」→「文件夹」，选择程序目录
  • 如已被删除，重新解压 ZIP 文件，先添加白名单，再运行
  • Windows：点击任务栏右侧的 「∧」展开箭头，查找隐藏图标区域
  • 如果确实没有图标，说明程序可能已崩溃，查看系统事件日志或尝试重新运行
  • 也可以打开任务管理器，确认 wandox-print-agent.exe 进程是否存在
  1. 打开「系统设置」→「隐私与安全性」
  2. 向下滚动到「安全性」区域，找到有关 WandoxPrintAgent 的提示
  3. 点击 「仍然打开」，输入系统密码
  4. 如果没有该按钮：在 Finder 中右键点击 .app → 选择「打开」→ 弹窗中点击「打开」

通过托盘菜单 → 「修改端口」更改主服务端口，改完后重启服务生效。

或者在命令行中指定端口运行：

wandox-print-agent.exe --port 9001

注意：修改端口后，业务系统中的 SDK 连接端口也需要同步更新。

HTTPS 页面需要使用 WSS（加密 WebSocket）连接，需完成证书信任（展开上方「HTTPS 页面使用」步骤）。

快速排查：

  1. 浏览器访问 https://127.0.0.1:9100，确认可以看到「证书已受信」字样
  2. 确认 SDK 使用了 tls: true 参数连接 WSS 端口
  3. Firefox 用户需额外操作（见上方证书信任步骤）

Chrome 128+ / Firefox 等浏览器升级后，默认限制网页通过 WebSocket 连接本地网络（Local Network Access，PNA），导致业务页面无法连接 Wandox 打印服务。需要在浏览器中关闭该项检查，每台电脑只需配置一次。

⚠️ 此配置会降低浏览器对本地网络访问的安全校验，仅用于本机打印场景。Chrome 官方后续版本可能移除该 flag，届时需改用其他方案。

① Chrome / Edge（Chromium 内核）

  1. 在地址栏输入并回车：chrome://flags/#local-network-access-check（Edge 用户输入 edge://flags/#local-network-access-check）
  2. 找到「Local Network Access Check」选项，将下拉框从 Default 改为 Disabled
  3. 点击页面右下角「Relaunch」按钮重启浏览器生效
chrome://flags
地址栏粘贴： chrome://flags/#local-network-access-check
Local Network Access Check chrome://flags/#local-network-access-check
Disabled ▼
👉 改完后点击右下角 Relaunch

② Firefox

  1. 在地址栏输入并回车：about:config，弹出风险提示页点击「接受风险并继续」
  2. 在搜索框输入：network.lna.enabled
  3. 点击该偏好项右侧的切换按钮，将值从 true 改为 false
  4. 重启 Firefox 生效
about:config
🔍 network.lna.enabled
network.lna.enabled
切换 false
⚠️ 修改高级配置可能影响 Firefox 功能，仅按本指引修改该项即可。
💡 配置完成后，建议刷新业务页面（Ctrl+Shift+R / Cmd+Shift+R 强制刷新）再重试打印。若仍无法连接，回到上方「检测服务是否正常运行」确认 Wandox 进程在线。

这是端口冲突导致的。常见旧打印插件与 Wandox 冲突的端口如下：

旧插件类型 占用端口 现象
CLodop / C-Lodop 8000 打印调用无响应
旧版易仓打印助手 8498 打印调用无响应或报错

解决方法：先彻底停止旧插件，再启动 Wandox。

  1. 在任务栏右下角（Windows）或菜单栏右上角（macOS）找到旧打印插件图标
  2. 右键点击 → 选择「退出」或「关闭」
  3. 打开任务管理器（Windows：Ctrl+Shift+Esc）或活动监视器（macOS），确认旧插件进程已不存在
  4. 重新启动 Wandox 打印助手
💡 建议在系统启动项中移除旧插件，避免下次开机再次冲突。Windows 可在任务管理器→「启动」标签页中禁用；macOS 在「系统设置→通用→登录项」中移除。
  • Windows：右键托盘图标 → 「开机自启动」（勾选即可）；或手动将 EXE 快捷方式放入 shell:startup 文件夹
  • macOS：点击菜单栏图标 → 「登录时启动」；或在「系统设置」→「通用」→「登录项」中添加

Wandox 打印助手

© 2026 易仓科技 ECCANG Technology 文档以最新版本为准