# 错误：无效的要求：'package==1.0'（requirements.txt 第 1 行）

- **ID:** `pip/requirements-file-bom`
- **领域:** pip
- **类别:** config_error
- **错误码:** `ERROR`
- **验证级别:** ai_generated
- **修复率:** 95%

## 根因

requirements.txt 文件开头包含 UTF-8 BOM（字节顺序标记）字符，pip 的解析器不会去除该字符，导致第一行被解释为无效的包名。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| pip 23.2 | active | — | — |
| pip 24.0 | active | — | — |
| Python 3.9 | active | — | — |
| Python 3.10 | active | — | — |
| Python 3.11 | active | — | — |

## 解决方案

1. ```
   Remove the BOM using a command-line tool: sed -i '1s/^\xef\xbb\xbf//' requirements.txt (Linux/macOS) or use PowerShell: (Get-Content requirements.txt) | Set-Content -Encoding UTF8NoBOM requirements.txt (Windows). Then retry pip install -r requirements.txt.
   ```
2. ```
   Recreate the requirements file without BOM: echo 'package==1.0' > requirements.txt && cat old_requirements.txt | tail -n +2 >> requirements.txt (skip first line with BOM).
   ```
3. ```
   Convert the file encoding using a Python script: python -c "with open('requirements.txt', 'r', encoding='utf-8-sig') as f: content = f.read(); with open('requirements.txt', 'w', encoding='utf-8') as f: f.write(content)" && pip install -r requirements.txt
   ```

## 无效尝试

- **** — Adding --no-cache-dir does not fix the BOM character in the file; it only affects pip's cache behavior. (98% 失败率)
- **** — Using pip install --upgrade pip does not change the file encoding; BOM remains. (95% 失败率)
- **** — Editing the file manually in a text editor may not remove the BOM if the editor adds it back (e.g., Notepad on Windows). (60% 失败率)