xiaohongshu_note_uploader/README.md

# 小红书笔记发布工具

一个简单易用的小红书图文/视频笔记自动发布工具，支持自动登录、内容填充、标签添加、定时发布等功能。

## ✨ 特性

- 📸 **图文笔记发布**：支持1-9张图片
- 🎬 **视频笔记发布**：支持视频笔记上传
- 🔐 **自动登录**：扫码登录一次，自动保存Cookie
- 🏷️ **智能标签**：自动添加话题标签
- ⏰ **定时发布**：支持设置发布时间
- 🤖 **人类化操作**：模拟真实用户行为，降低风控风险
- 🚀 **简单易用**：几行代码即可完成发布

## 📦 安装

### 1. 环境要求

- Python 3.11+
- macOS / Windows / Linux

### 2. 安装依赖

```bash
# 克隆或下载项目
cd xiaohongshu_note_publisher

# 安装Python依赖
pip install playwright loguru

# 安装浏览器驱动
playwright install chromium
```

## 🚀 快速开始

### 发布图文笔记

```python
import asyncio
from publisher import XiaoHongShuImageNote

async def main():
    # 创建图文笔记上传器
    note = XiaoHongShuImageNote(
        title="周末去哪玩 ✨",
        content="今天天气真好，推荐大家去公园走走～",
        tags=["#广州", "#周末", "#出游"],
        image_paths=["photo1.jpg", "photo2.jpg"],
        publish_date=0,  # 0表示立即发布
        account_file="cookies/account.json"
    )
    
    # 执行发布
    await note.main()
    print("✅ 发布成功！")

if __name__ == "__main__":
    asyncio.run(main())
```

### 发布视频笔记

```python
import asyncio
from publisher import XiaoHongShuVideoNote

async def main():
    # 创建视频笔记上传器
    note = XiaoHongShuVideoNote(
        title="分享日常 vlog",
        content="今天的生活记录～",
        tags=["#vlog", "#日常"],
        video_path="my_video.mp4",
        publish_date=0,
        account_file="cookies/account.json"
    )
    
    await note.main()
    print("✅ 发布成功！")

if __name__ == "__main__":
    asyncio.run(main())
```

## 📖 详细使用

### 参数说明

#### XiaoHongShuImageNote（图文笔记）

| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| `title` | str | ✅ | 笔记标题（最多30字） | "周末去哪玩" |
| `content` | str | ✅ | 笔记正文（最多1000字） | "今天天气真好..." |
| `tags` | List[str] | ✅ | 话题标签（最多3个） | ["#广州", "#周末"] |
| `image_paths` | List[str] | ✅ | 图片路径列表（1-9张） | ["1.jpg", "2.jpg"] |
| `publish_date` | int/datetime | ✅ | 发布时间，0表示立即发布 | 0 或 datetime对象 |
| `account_file` | str | ✅ | Cookie文件路径 | "cookies/account.json" |
| `location` | str | ❌ | 地理位置 | "广州塔" |
| `cover_index` | int | ❌ | 封面图索引（0-8） | 0 |
| `filter_name` | str | ❌ | 滤镜名称 | "自然" |
| `headless` | bool | ❌ | 是否无头模式 | False |

#### XiaoHongShuVideoNote（视频笔记）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | str | ✅ | 笔记标题 |
| `content` | str | ✅ | 笔记正文 |
| `tags` | List[str] | ✅ | 话题标签 |
| `video_path` | str | ✅ | 视频文件路径 |
| `publish_date` | int/datetime | ✅ | 发布时间 |
| `account_file` | str | ✅ | Cookie文件路径 |
| `location` | str | ❌ | 地理位置 |
| `headless` | bool | ❌ | 是否无头模式 |

### 定时发布示例

```python
from datetime import datetime, timedelta

# 设置明天下午3点发布
tomorrow_3pm = datetime.now() + timedelta(days=1)
tomorrow_3pm = tomorrow_3pm.replace(hour=15, minute=0, second=0)

note = XiaoHongShuImageNote(
    title="明天见～",
    content="提前准备好的内容",
    tags=["#生活"],
    image_paths=["photo.jpg"],
    publish_date=tomorrow_3pm,  # 使用datetime对象
    account_file="cookies/account.json"
)
```

### 添加地理位置

```python
note = XiaoHongShuImageNote(
    title="打卡广州塔",
    content="来广州必打卡的地标！",
    tags=["#广州", "#旅行"],
    image_paths=["guangzhou_tower.jpg"],
    publish_date=0,
    account_file="cookies/account.json",
    location="广州塔"  # 添加地理位置
)
```

## 🔐 首次使用（获取Cookie）

第一次运行时，工具会自动打开浏览器：

1. 🖥️ 浏览器自动打开小红书登录页面
2. 📱 使用小红书App扫描二维码登录
3. ✅ 登录成功后，Cookie自动保存
4. 🎉 下次使用直接读取Cookie，无需重复登录

```python
# 首次运行会自动打开浏览器让你扫码
# Cookie会保存到指定路径
await note.main()  # 自动处理登录流程
```

## 📁 项目结构

```
xiaohongshu_note_publisher/
├── README.md              # 本文件
├── publisher.py           # 主程序
├── utils.py              # 工具函数
├── requirements.txt      # 依赖列表
├── example_image.py      # 图文笔记示例
├── example_video.py      # 视频笔记示例
├── quick_test.py         # 快速测试脚本
└── cookies/              # Cookie存储目录
    └── account.json
```

## 🔍 常见问题

### 1. Cookie失效怎么办？

删除Cookie文件，重新运行程序会自动打开浏览器让你重新登录：

```bash
rm cookies/account.json
python example_image.py  # 重新运行
```

### 2. 上传失败怎么办？

- 检查网络连接
- 确认Cookie有效
- 查看错误截图（自动保存）
- 确认图片/视频文件存在

### 3. 如何批量发布？

```python
import asyncio
from publisher import XiaoHongShuImageNote

async def batch_publish():
    posts = [
        {"title": "标题1", "images": ["1.jpg"], "tags": ["#tag1"]},
        {"title": "标题2", "images": ["2.jpg"], "tags": ["#tag2"]},
    ]
    
    for post in posts:
        note = XiaoHongShuImageNote(
            title=post["title"],
            content=post["title"],
            tags=post["tags"],
            image_paths=post["images"],
            publish_date=0,
            account_file="cookies/account.json"
        )
        await note.main()
        await asyncio.sleep(30)  # 每次发布间隔30秒，避免风控

asyncio.run(batch_publish())
```

### 4. 支持多账号吗？

支持！为每个账号准备不同的Cookie文件：

```python
# 账号1
note1 = XiaoHongShuImageNote(
    ...,
    account_file="cookies/account1.json"
)

# 账号2
note2 = XiaoHongShuImageNote(
    ...,
    account_file="cookies/account2.json"
)
```

## ⚠️ 注意事项

1. **发布频率**：建议每次发布间隔30秒以上，避免触发平台风控
2. **内容质量**：确保发布内容符合小红书社区规范
3. **图片要求**：支持jpg、png格式，建议分辨率1080x1080以上
4. **视频要求**：支持mp4格式，建议1080P以上
5. **Cookie安全**：妥善保管Cookie文件，不要泄露给他人

## 🛠️ 高级功能

### 使用有头模式（推荐新手）

```python
note = XiaoHongShuImageNote(
    ...,
    headless=False  # 可以看到浏览器操作过程
)
```

### 自定义封面

```python
note = XiaoHongShuImageNote(
    ...,
    image_paths=["img1.jpg", "img2.jpg", "img3.jpg"],
    cover_index=1  # 使用第2张图片作为封面（索引从0开始）
)
```

## 📝 更新日志

### v1.0.0 (2025-11-07)

- ✨ 首次发布
- 📸 支持图文笔记发布
- 🎬 支持视频笔记发布
- 🔐 自动Cookie管理
- ⏰ 支持定时发布
- 🤖 人类化操作

## 📄 许可

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 💬 联系方式

如有问题，欢迎通过Issue联系。

---

**⚡ 快速开始：** 运行 `python quick_test.py` 立即体验！