# 西羊石AI微信插件 | WeChat Node for n8n

![NPM Version](https://img.shields.io/npm/v/n8n-nodes-weixin-wechat?style=flat-square&logo=npm)
![NPM Downloads](https://img.shields.io/npm/dt/n8n-nodes-weixin-wechat?style=flat-square&logo=npm)
![License](https://img.shields.io/npm/l/n8n-nodes-weixin-wechat?style=flat-square)

**让你的N8N支持微信消息发送！** 📱✨

> ✨ **v1.2.23新版**：重大功能修复！个人微信文件传输完美支持文件路径自动提取和说明文字传递，解决用户反馈的核心问题！

---

## 🎥 **功能演示视频**

### 📁 文件批量发送演示
https://github.com/Standed/n8n-nodes-weixin-wechat/raw/main/文件批量发送.mp4

*演示如何使用N8N工作流批量发送文件到多个微信联系人，支持智能延迟和随机化发送*

### 🤖 数字人二进制发送演示
https://github.com/Standed/n8n-nodes-weixin-wechat/raw/main/数字人二进制方式发送.mp4

*演示AI数字人生成的内容通过二进制数据直接发送到微信，展示完整的AI工作流集成*

> 💡 **提示**：点击链接可直接下载观看演示视频，看到真实的使用效果！

---

## 🎯 你想用微信做什么？

### 🙋‍♂️ 真实个人微信发送 (推荐)
**适合：需要发送到个人联系人、工作群、朋友群**
- ✅ 真实微信控制，不会被限制  
- ✅ 发送给任何联系人/群聊
- ✅ 支持文本、图片、文件、视频等
- ✅ URL文件下载发送
- ✅ 二进制文件处理
- ✅ 批量发送，智能延迟
- 🎯 **[3分钟快速开始 →](#-个人微信3分钟快速开始)**

### 🏢 企业微信群机器人
**适合：只需要发送到企业微信工作群**
- ✅ 无需额外部署，配置即用
- ✅ 支持文本和Markdown消息
- ✅ 官方API，稳定可靠
- 🎯 **[1分钟快速开始 →](#-企业微信1分钟快速开始)**

---

## 🚀 个人微信3分钟快速开始

### 第1步：安装插件 (30秒)
1. N8N → **设置** → **社区节点** → **安装**
2. 输入：`n8n-nodes-weixin-wechat`
3. 等待安装完成

### 第2步：获取API密钥 (30秒)
1. 关注微信公众号：**"西羊石AI视频"**
2. 发送：**"API"**
3. 复制收到的密钥

### 第3步：准备系统环境
**⚠️ 微信版本要求**：
- ✅ **推荐版本**：微信PC版 3.9.8 - 3.9.12 
- ❌ **不支持**：微信4.0版本（暂不兼容）
- 📥 **下载地址**：
  - [微信官网](https://pc.weixin.qq.com/?lang=en_US) 
  - [百度网盘 微信3.9.12版本](https://pan.baidu.com/s/1j2p3NTdjSexbQVPQD3Wopg) 提取码: d7j4

**系统要求**：
- Windows 10+ 或 Windows Server 2016+
- Python 3.9-3.12 (会自动安装)

### 第4步：下载PC服务 (2分钟)
1. 访问：https://github.com/Standed/n8n-nodes-weixin-wechat
2. 下载到Windows电脑，进入 `personal-wechat-service` 目录
3. **双击运行**：`一键启动.bat`
4. 如提示缺少环境，会自动打开下载页面

### 第5步：配置N8N服务地址 ⚠️ 重要
**根据你的N8N部署方式选择对应配置：**

#### 📍 情况1：本地安装N8N (Windows/Mac)
- N8N和个人微信服务在同一台电脑
- **个人微信服务地址**：`http://127.0.0.1:3000`
- 💡 **为什么不用localhost？** 部分系统可能无法解析localhost域名，使用IP地址更稳定

#### 📍 情况2：本地Docker运行N8N
- N8N在Docker容器中，个人微信服务在宿主机Windows
- **个人微信服务地址**：`http://host.docker.internal:3000`

#### 📍 情况3：云端/远程N8N (VPS/云服务器)
- N8N在云服务器，个人微信服务在本地Windows
- **需要内网穿透**：推荐使用 [ngrok](https://ngrok.com/) 或 [frp](https://github.com/fatedier/frp)
- **个人微信服务地址**：穿透后的地址，如 `https://abc123.ngrok.io`

**配置步骤**：
1. 新建凭据 → **西羊石AI微信插件 API**
2. **API Key**：粘贴第2步获取的密钥
3. **个人微信服务地址**：根据上方情况选择对应地址

### 🎉 开始使用！
- 工作流中添加 **WeChat Send** 节点
- 选择 **个人微信自动化**
- 发送到 **联系人**、**群聊** 或 **文件传输助手**

---

## 🏢 企业微信1分钟快速开始

### 第1步：安装插件 (30秒)
同个人微信第1步

### 第2步：获取API密钥 (30秒)
同个人微信第2步

### 第3步：获取企业微信Webhook
1. 企业微信群 → **群设置** → **机器人** → **添加机器人**
2. 复制生成的Webhook地址

### 第4步：配置使用
1. N8N工作流中添加 **WeChat Send** 节点
2. 选择 **企业微信机器人**
3. 粘贴Webhook地址，选择消息类型（文本/Markdown/图片/文件/图文）
4. 发送消息测试

---

## 📋 功能对比

| 功能特性 | 🙋‍♂️ 个人微信 | 🏢 企业微信 |
|---------|:----------:|:----------:|
| 发送对象 | 任何联系人/群聊 | 企业微信群 |
| 消息类型 | 文本/图片/文件/视频等 | 文本/Markdown/图片/文件/图文 |
| 图片发送 | ✅ 完整支持 | ✅ 支持URL图片 |
| 文件发送 | ✅ 完整支持 | ✅ 支持URL文件 |
| 图文消息 | ❌ 不支持 | ✅ 支持图文卡片 |
| URL文件 | ✅ 自动下载发送 | ✅ 自动上传发送 |
| 部署要求 | 需PC服务 | 无需部署 |
| 被限制风险 | 极低(真实微信) | 无 |
| 功能丰富度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 使用难度 | ⭐⭐⭐ | ⭐ |

---

## 🔧 高级配置

### 云端N8N内网穿透详细方案 🌐
**问题**：云端N8N无法直接访问您本地Windows的3000端口

**💡 解决方案（3选1）**：

#### 方案1：ngrok（推荐新手）⭐
1. 下载：https://ngrok.com/download
2. 运行：`ngrok http 3000`
3. 复制生成的URL，如：`https://abc123.ngrok.io`
4. N8N凭证中设置：`https://abc123.ngrok.io`

#### 方案2：frp（推荐技术用户）⭐⭐⭐
1. 下载：https://github.com/fatedier/frp/releases
2. 配置frpc.ini连接到您的服务器
3. 启动：`frpc.exe -c frpc.ini`
4. N8N凭证中设置您的域名地址

#### 方案3：NATAPP（国内用户）⭐⭐
1. 注册：https://natapp.cn/
2. 下载客户端，配置tunnel
3. 启动隧道映射到本地3000端口
4. 使用分配的域名地址

**📋 选择建议**：
- **测试使用**：ngrok免费版
- **生产使用**：frp自建服务器
- **国内用户**：NATAPP速度更快

### 批量发送设置
- **发送间隔**：建议3-5秒（避免限制）
- **随机延迟**：增加真实性
- **失败重试**：自动重试机制

---

## 🆘 遇到问题？

### 安装相关
❓ **插件安装失败？**
- 重启N8N后重新安装
- 检查N8N版本是否>=0.160.0

❓ **凭据配置错误？**  
- API Key：确保从公众号正确获取
- 服务地址：检查PC服务是否正常运行

### 个人微信相关
❓ **PC服务启动失败？**
- 检查Python和Node.js环境
- 查看 `personal-wechat-service/新手指南.md`

❓ **微信发送失败？**
- 确保PC微信已登录
- 联系人名称要完全匹配

### 企业微信相关
❓ **Webhook无效？**
- 重新在企业微信群中生成
- 检查URL格式是否正确

---

## 📞 获取帮助

- 🏠 **官网**：https://xysaiai.cn/
- 📱 **公众号**：西羊石AI视频
- 💬 **技术支持**：公众号发送"帮助"
- 🐛 **问题反馈**：[GitHub Issues](https://github.com/Standed/n8n-nodes-weixin-wechat/issues)

---

## 📝 更新日志

### v1.2.27 (最新) 🎉
- 🔥 **企业微信机器人功能大幅增强**：新增图片、文件、图文消息支持
- 📷 **图片消息**：支持通过URL发送图片到企业微信群，自动处理base64编码
- 📎 **文件消息**：支持文档、压缩包等文件上传，自动获取media_id并发送
- 📰 **图文消息**：支持发送图文卡片，最多8个图文项，包含标题、描述、链接、图片
- 🎯 **节点名称**：在N8N中添加名为 **WeChat Send** 的节点
- ✨ **体验优化**：企业微信功能从⭐⭐⭐提升至⭐⭐⭐⭐，媲美个人微信

### v1.2.23 🎉
- 🔧 **重大修复**：个人微信文件传输路径处理优化，完美解决文件名提取问题
- 📝 **功能增强**：完整支持Caption/Description说明文字传递到个人微信
- 🐛 **Bug修复**：修复文件路径如`/data/files/1/3.mp4`无法正确提取为`3.mp4`的问题
- ✨ **体验提升**：N8N Additional Options中的说明文字现在可以正确发送到微信
- 🛠️ **代码优化**：增强Node.js与Python服务间的参数传递完整性

### v1.2.22
- 🚀 **一键启动完美修复**：彻底移除BAT脚本中的所有pause命令，实现真正的双击即启动
- 🔧 **用户体验革命性提升**：从"双击→按键→退出→再次双击"优化为"双击→自动完成"
- ⚡ **智能错误处理**：所有错误情况都采用自动超时(5秒)，无需用户手动按键确认
- 🎯 **部署体验无缝化**：Windows用户现在享受真正零交互的自动化部署体验
- ✅ **测试验证完成**：确认文件发送功能(URL和二进制)在各种N8N部署环境下正常工作

### v1.2.20
- 🚀 **重大功能更新**：个人微信文件发送功能完整实现！彻底解决云端N8N文件发送报错问题
- 📎 **文件发送支持**：完整支持图片、文档、视频、音频等所有文件类型发送
- 🌐 **URL文件下载**：支持URL文件自动下载并发送，无需手动下载
- 💾 **二进制数据处理**：完美兼容N8N二进制数据格式，云端服务器直接可用
- 🔧 **技术架构升级**：集成wxauto SendFiles API，增加requests依赖，智能临时文件管理
- 🧪 **完整测试支持**：提供功能测试和API测试脚本，确保功能稳定性
- 📋 **文档完善**：更新API文档、使用说明和功能对比表格
- 🎯 **用户体验提升**：解决了用户反馈的核心痛点，文件发送功能现已完全可用

### v1.2.19
- 🔒 **稳定性增强**：优化API Key验证逻辑，确保个人微信功能的稳定性和一致性
- 🛡️ **体验优化**：完善身份验证流程，提升用户使用个人微信功能时的可靠性
- 🎨 **图标优化**：重新设计微信图标，提升视觉效果和兼容性
- 💫 **用户体验**：优化个人微信服务连接机制，确保功能正常运行
- ✅ **企业微信完善**：企业微信功能持续优化，使用更加便捷流畅

### v1.2.18
- 🔥 **重大转化优化**：强化API Key获取引导，显著提升公众号转化率
- 🎯 **优化用户流程**：个人微信部署引导将"获取API Key"置于首位，避免用户遗漏
- 💡 **智能错误提醒**：接口报错时自动提供公众号获取API Key的详细指引  
- 🔑 **强化凭据引导**：凭据配置页面添加分步骤API Key获取说明，降低使用门槛
- ✅ **保持功能完整**：所有现有功能保持正常，不影响企业微信和个人微信使用

### v1.2.17
- 🔧 **修复图标显示**：解决n8n界面中图标不显示的问题，优化构建流程自动复制图标到正确目录
- 📦 **改进构建**：新增copy-icons脚本，确保图标文件正确包含在发布包中
- ✅ **完善测试**：企业微信webhook功能测试通过，文本和markdown消息类型均正常工作


### v1.2.16
- 🔧 **修复企业微信**：解决企业微信发送时弹出个人微信的问题，企业微信现在直接调用webhook
- 🎨 **优化图标**：简化SVG图标结构，提高n8n中的显示兼容性
- 🔍 **隔离修复**：企业微信不再经过requestWithAuth，避免与个人微信服务路由冲突
- ✅ **双功能正常**：企业微信和个人微信现在都可以正常使用！

### v1.2.15
- 🔥 **热修复**：解决“微信客户端未启动或未登录”错误，移除Python脚本中错误的UiaAPI检测
- ✅ **功能正常**：个人微信发送功能现在真正可以正常使用了！
- 🛠️ **优化逻辑**：依赖wxauto库的内部错误处理，更简洁可靠

### v1.2.14
- 🎆 **最终解决**：Docker环境下个人微信发送完美支持，优先使用凭证中配置的serviceUrl
- 🛠️ **架构优化**：移除节点表单中的服务地址配置，统一使用凭证配置
- 🔧 **企业微信修复**：企业微信同步修复连接问题，现在可正常使用
- 📝 **启动体验**：改进.bat脚本，解决第一次运行退出问题

### v1.2.13
- 🔥 **关键修复**：修复个人微信发送“连接被拒绝”问题，节点默认端口从3001改为3000
- 🔌 **端口统一**：所有组件(节点/credential/服务/文档)统一使用3000端口
- 📝 **JSON解析修复**：移除Python日志stdout输出，解决“不是有效的JSON”错误  
- 🎆 **功能正常**：个人微信发送现在可以正常使用了！

### v1.2.12
- 🔧 **修复核心bug**：personal-wechat-service端口从3001改为3000，与credential配置保持一致
- 🛠️ **改进启动脚本**：修复中文乱码显示，增强错误处理和调试信息
- 📝 **优化用户体验**：显示实际服务端口和健康检查地址
- 🌐 **双语支持**：保留中文版一键启动.bat和英文版start-english.bat

### v1.2.11
- 🔧 **修复凭证端口问题**：默认端口从3001改为3000
- 🐳 解决Docker环境n8n-workflow依赖问题
- ✅ 优化TypeScript构建流程
- 📋 同步更新README.md端口配置
- 🗂️ 清理项目冗余文件，减小包体积

### v1.2.6
- 🎉 **重大体验升级**：全新用户引导界面
- 🙋‍♂️ 主推个人微信功能，使用面更广
- ✅ 优化凭证配置，解决API Key混淆问题  
- 🚀 新增一键部署脚本，3分钟上手
- 📖 重构文档，按需求场景分流引导
- 🛠️ 优化节点界面，清晰展示功能特点

### v1.2.5
- 🐛 **重要修复**：解决N8N安装时的EACCES权限错误
- ✅ 优化包体积：从44.1kB减少到29.7kB
- ✅ 提升安装成功率和稳定性
- 🔧 完善构建流程和文件管理

### v1.2.4
- 🐛 尝试修复权限问题（部分解决）

### v1.2.3
- ✅ 新增真实个人微信自动化（基于wxauto）
- ✅ 企业微信支持Markdown消息
- ✅ 固定端口凭证验证
- ✅ 完善跨平台部署支持

---

## 📄 开源协议

MIT License - 详见 [LICENSE](LICENSE) 文件

---

<div align="center">

**⭐ 觉得好用？给个Star支持一下！**

**🌟 让你的N8N工作流更智能！**

Made with ❤️ by [西羊石AI](https://xysaiai.cn)

</div>