autoUpload/docs/xhs_note_uploader_quickstart.md

小红书笔记上传器 - 快速开始指南

🚀 5分钟上手

第一步：安装依赖

cd /Users/yarrow/autoUpload
pip install -r requirements.txt
playwright install chromium

第二步：获取Cookie

python examples/get_xiaohongshu_cookie.py

扫码登录后，Cookie会自动保存到 cookies/xiaohongshu_note/account.json

第三步：上传图文笔记

import asyncio
from pathlib import Path
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def main():
    note = XiaoHongShuImageNote(
        title="我的第一条笔记✨",
        content="测试上传功能～",
        tags=["测试", "分享"],
        image_paths=["videos/demo.png"],
        publish_date=0,  # 0=立即发布
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False  # 有头模式，可以看到浏览器操作
    )
    await note.main()

asyncio.run(main())

---

📋 核心参数说明

参数	说明	示例
title	标题（最多30字）	"今天的下午茶☕️"
content	正文（最多1000字）	"分享一下..."
tags	话题标签（建议≤3个）	["下午茶", "咖啡"]
image_paths	图片列表（1-9张）	["1.jpg", "2.jpg"]
publish_date	发布时间	0（立即）或datetime（定时）
account_file	Cookie路径	"cookies/account.json"
location	地点（可选）	"上海市·静安区"
headless	无头模式	False（推荐有头）

---

📝 完整示例

示例1：立即发布（单图）

import asyncio
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_single_image():
    note = XiaoHongShuImageNote(
        title="早安☀️",
        content="新的一天开始啦～",
        tags=["早安", "日常"],
        image_paths=["morning.jpg"],
        publish_date=0,
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False
    )
    await note.main()

asyncio.run(upload_single_image())

示例2：立即发布（多图）

import asyncio
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_multiple_images():
    note = XiaoHongShuImageNote(
        title="今日穿搭分享👗",
        content="给大家分享一下今天的穿搭～\n简约又时尚！",
        tags=["穿搭", "时尚", "OOTD"],
        image_paths=["look1.jpg", "look2.jpg", "look3.jpg"],
        publish_date=0,
        account_file="cookies/xiaohongshu_note/account.json",
        location="北京市·朝阳区",
        headless=False
    )
    await note.main()

asyncio.run(upload_multiple_images())

示例3：定时发布

import asyncio
from datetime import datetime, timedelta
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_scheduled():
    # 明天上午10点发布
    tomorrow_10am = datetime.now() + timedelta(days=1)
    tomorrow_10am = tomorrow_10am.replace(hour=10, minute=0, second=0)
    
    note = XiaoHongShuImageNote(
        title="明日预告📢",
        content="明天10点见～",
        tags=["预告", "明天见"],
        image_paths=["preview.jpg"],
        publish_date=tomorrow_10am,  # 定时发布
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False
    )
    await note.main()

asyncio.run(upload_scheduled())

示例4：批量上传（安全间隔）

import asyncio
import random
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def batch_upload():
    notes_data = [
        {
            "title": "笔记1",
            "content": "内容1",
            "tags": ["标签1"],
            "images": ["1.jpg"],
        },
        {
            "title": "笔记2",
            "content": "内容2",
            "tags": ["标签2"],
            "images": ["2.jpg"],
        },
    ]
    
    for i, data in enumerate(notes_data):
        print(f"\n上传第 {i+1}/{len(notes_data)} 条笔记...")
        
        note = XiaoHongShuImageNote(
            title=data["title"],
            content=data["content"],
            tags=data["tags"],
            image_paths=data["images"],
            publish_date=0,
            account_file="cookies/xiaohongshu_note/account.json",
            headless=False
        )
        
        await note.main()
        
        # 间隔10-15分钟
        if i < len(notes_data) - 1:
            wait_min = random.randint(10, 15)
            print(f"⏰ 等待 {wait_min} 分钟...")
            await asyncio.sleep(wait_min * 60)

asyncio.run(batch_upload())

---

⚙️ 优化后的新特性

1. 批量图片上传

# 一次性上传多张图片（更快！）
image_paths=["1.jpg", "2.jpg", "3.jpg", "4.jpg", "5.jpg"]

2. 精准元素定位

# 使用优化后的选择器，定位成功率 95%+
# 自动适配小红书最新页面结构

3. 智能等待机制

# 自动等待图片预览加载完成
# 显示实时进度：已加载 3/5 张图片

4. 人类化输入

# 三种速度模式：
# - 标题：80-150ms/字符
# - 正文：100-200ms/字符  
# - 标签：500-800ms/字符（极慢，防检测）

---

🛡️ 安全建议

✅ 推荐配置

{
    'headless': False,          # 有头模式
    'tags_limit': 3,            # 最多3个标签
    'upload_interval': 600,     # 间隔10分钟
    'max_notes_per_day': 5,     # 每天最多5条
}

❌ 不推荐配置

{
    'headless': True,           # 无头模式不稳定
    'upload_interval': 60,      # 间隔太短
    'max_notes_per_day': 20,    # 数量太多，易触发风控
}

---

🐛 常见问题

Q1: 找不到上传元素？

A: 使用有头模式检查页面是否正确加载

headless=False  # 设置为False观察浏览器

Q2: Cookie失效？

A: 重新获取Cookie

from uploader.xhs_note_uploader.main import xiaohongshu_note_cookie_gen
await xiaohongshu_note_cookie_gen("cookies/account.json")

Q3: 标签输入无效？

A:

• 减少标签数量（≤3个）
• 使用简短标签文字
• 确保标签不包含特殊字符

Q4: 图片上传慢？

A:

• 优化图片大小（建议<5MB）
• 使用常见格式（.jpg, .png）
• 检查网络连接

---

📖 更多资源

• 详细文档: docs/xhs_note_uploader_optimization.md
• 设计文档: docs/xhs_note_uploader_design.md
• 完整示例: examples/upload_note_to_xiaohongshu_image.py
• 测试脚本: examples/test_xhs_note_uploader.py

---

🎯 下一步

1. 测试上传: 运行测试脚本验证功能

python examples/test_xhs_note_uploader.py

2. 查看日志: 检查上传详细日志

# 日志包含每个步骤的执行情况

3. 优化内容: 根据需求调整标题、正文、标签

# 真实、有价值的内容更容易获得推荐

4. 定期维护: 定期手动登录维持账号活跃度

# 建议每周至少手动登录一次

---

💡 专业提示

1. 图片质量: 使用高质量、原创图片
2. 文案优化: 标题要吸引人，正文要真诚
3. 标签选择: 选择精准、热门的话题标签
4. 发布时间: 选择用户活跃时段（早8点、午12点、晚8点）
5. 互动维护: 及时回复评论，提高互动率

---

祝你使用愉快！ 🎉