# 微信公众号开发 - 配置文件说明

本文档详细介绍 xqcwechat 的环境变量配置和 Token 获取方式。

## 快速开始

### 方式一：使用 Token Secret（最简配置）

只需要配置一个环境变量即可开始使用：

```env
# 配合自建的 access_token 管理API使用
# 详细部署文档：https://xiaoqiangclub.blog.csdn.net/article/details/155324712
WECHAT_TOKEN_SECRET=your_secret_key
```

然后在代码中：

```python
from xqcwechat import Auth

# 自动检测到 WECHAT_TOKEN_SECRET 后，会自动使用默认回调函数获取 token
auth = Auth()
```

### 方式二：使用微信官方 API

```env
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```

```python
from xqcwechat import Auth

auth = Auth()
```

### 方式三：使用智能加载（推荐）

```python
from xqcwechat import Auth

# 自动检测环境变量，智能选择 Token 获取方式
auth = Auth.from_env()
```

## 环境变量配置

### 加载顺序

环境变量加载优先级（后面的覆盖前面的）：

1. **当前工作目录的 `.env`**（用户项目根目录）- **最高优先级**
2. **xqcwechat-skill 目录的 `.env`**（如果存在）
3. **项目根目录的 `.env`**
4. **系统环境变量**

### Token 获取方式配置

| 变量名 | 必填 | 说明 | 示例 |
| --------------------- | ---- | --------------------------------------------------------------------- | ---------------------------------- |
| `WECHAT_TOKEN_SECRET` | 否 | Token 密钥，配合方式二使用 | `your_secret_key` |
| `WECHAT_TOKEN_URL` | 否 | Token API 地址 | `https://your-api.com/token` |
| `WECHAT_TOKEN_APP_ID` | 否 | 微信公众号 AppID（可选，不指定则使用默认的 XiaoqiangClub Token 服务） | `wx44bbxxxxxxx8888` |
| `WECHAT_APP_ID` | 否\* | 微信公众号 AppID（方式一） | `wx44bbxxxxxxx8888` |
| `WECHAT_APP_SECRET` | 否\* | 微信公众号 AppSecret（方式一） | `c9f743480b9debxxxx8440c4b8888253` |

> \*注：`WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 至少需要一个，除非已配置 `WECHAT_TOKEN_SECRET`。

### 代理配置

| 变量名 | 说明 | 示例 |
| -------------- | -------------- | ----------------------- |
| `WECHAT_PROXY` | 代理服务器地址 | `http://127.0.0.1:7890` |

### 多账号配置

统一使用 `WECHAT_ACCOUNT_N_xxx` 格式，只需配置一个账号时就是单账号。

#### 方式一：使用微信官方 API

```env
# 账号1（只需配置一个就是单账号）
WECHAT_ACCOUNT_1_APP_ID=wx44bbxxxxxxx8888
WECHAT_ACCOUNT_1_APP_SECRET=c9f743480b9debxxxx8440c4b8888253
WECHAT_ACCOUNT_1_NAME=我的公众号1

# 账号2（可按需添加更多账号）
WECHAT_ACCOUNT_2_APP_ID=wx55ccyyyyyyy9999
WECHAT_ACCOUNT_2_APP_SECRET=d8g654591c0fga1119551d5c9999364
WECHAT_ACCOUNT_2_NAME=我的公众号2
```

#### 方式二：使用默认回调函数

共用一个 Token 服务密钥，每个账号配置不同的 app_id：

```env
# 共用配置：Token 服务密钥（必填）
WECHAT_TOKEN_SECRET=your_secret_key

# 账号1（只需配置一个就是单账号）
WECHAT_ACCOUNT_1_TOKEN_APP_ID=wx_account_1_appid

# 账号2（可按需添加更多账号）
WECHAT_ACCOUNT_2_TOKEN_APP_ID=wx_account_2_appid
```

使用示例：

```python
from xqcwechat import Auth

# 账号1
auth1 = Auth.from_env("1")

# 账号2
auth2 = Auth.from_env("2")
```

#### 方式三：使用自定义回调函数

```env
# 使用自定义回调函数时，指定每个账号使用的模块
WECHAT_ACCOUNT_1_TOKEN_GETTER_MODULE=token_getters.account_1
WECHAT_ACCOUNT_2_TOKEN_GETTER_MODULE=token_getters.account_2
```

## Token 获取方式详解

### 优先级说明

Token 获取优先级从高到低：

1. **自定义回调函数** - `WECHAT_ACCOUNT_N_TOKEN_GETTER_MODULE` 环境变量
2. **Token Secret** - `WECHAT_TOKEN_SECRET` 环境变量
3. **微信官方 API** - `WECHAT_ACCOUNT_N_APP_ID` + `WECHAT_ACCOUNT_N_APP_SECRET`

### 方式一：微信官方 API（默认）

直接使用微信公众平台的 AppID 和 AppSecret 获取 Token：

```env
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```

```python
from xqcwechat import Auth
auth = Auth() # 自动从环境变量加载
```

### 方式二：使用默认回调函数（推荐）

配置 Token 服务地址，只需一个密钥即可：

```env
WECHAT_TOKEN_SECRET=your_secret_key
WECHAT_TOKEN_URL=https://your-token-service.com/token
WECHAT_TOKEN_APP_ID=your_app_id # 可选，不指定则使用默认服务
```

```python
from xqcwechat import Auth
auth = Auth() # 自动检测并使用回调函数
```

**或者使用智能加载：**

```python
from xqcwechat import Auth
auth = Auth.from_env() # 推荐，自动检测配置
```

### 方式三：使用自定义回调函数

```python
from functools import partial
from xqcwechat import Auth

def get_token(secret: str, api_url: str):
    import requests
    resp = requests.get(api_url, params={"secret": secret})
    return resp.json()

auth = Auth(
    access_token_getter=partial(get_token, secret="xxx", api_url="https://api.com/token")
)
```

## 代码中的配置加载

### 方式一：直接使用环境变量

```python
import os
from xqcwechat import Auth

auth = Auth(
    app_id=os.getenv("WECHAT_APP_ID"),
    app_secret=os.getenv("WECHAT_APP_SECRET"),
    proxy=os.getenv("WECHAT_PROXY")
)
```

### 方式二：使用 dotenv 加载（推荐）

```python
from dotenv import load_dotenv
load_dotenv() # 加载 .env 文件

from xqcwechat import Auth
auth = Auth() # 自动从环境变量加载
```

### 方式三：使用 from_env 智能加载（最推荐）

```python
from xqcwechat import Auth

# 自动检测配置方式：
# - 有 WECHAT_TOKEN_SECRET → 使用回调函数
# - 有 WECHAT_APP_ID + WECHAT_APP_SECRET → 使用官方 API
# - 有多账号配置 → 使用指定账号
auth = Auth.from_env()

# 指定账号
auth2 = Auth.from_env("2") # 使用 WECHAT_ACCOUNT_2_ 配置
```

### 方式四：使用 AccountManager（多账号）

```python
from xqcwechat import AccountManager

manager = AccountManager()

draft = manager.get_draft()
draft2 = manager.get_draft("账号2")
```

## 常见问题

### Q: 配置了 WECHAT_TOKEN_SECRET 但还是报错？

确保：

1. `WECHAT_TOKEN_SECRET` 环境变量已正确配置
2. 如果使用方式一（官方 API），需要同时配置 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET`

### Q: 如何清除 Token 缓存？

```python
auth = Auth()
auth.clear_cache() # 清除缓存
```

### Q: 如何调试 Token 获取？

```python
auth = Auth()
token = auth.get_access_token()
print(token)
```

### Q: 多账号发布草稿时，如何将同一篇文章发布到多个账号？

使用多账号发布脚本：

```bash
# 创建草稿并发布到所有账号
python -m xqcwechat.scripts.quick_create_draft_multi "标题" "内容" cover.jpg

# 或指定特定账号
python -m xqcwechat.scripts.quick_create_draft_multi "标题" "内容" cover.jpg "1,2"

# 发布已创建的草稿到多个账号
python -m xqcwechat.scripts.quick_publish media_id "标题" "1,2"
```
