docs: 更新文档和技能

i18n/zh/documents/常见坑汇总/README.md

@@ -14,6 +14,101 @@
 | AI 幻觉，编造不存在的 API | 模型知识过时 | 提供官方文档链接，让 AI 参考 |
 | 代码越改越乱 | 没有规划 | 先让 AI 出方案，确认后再写代码 |
 | AI 不理解我的需求 | 描述模糊 | 用具体例子说明，给输入输出示例 |
+| AI 忘记之前的对话 | 上下文丢失 | 重新提供关键信息，或用 memory bank |
+| AI 改了不该改的代码 | 指令不明确 | 明确说"只改 xxx，不要动其他文件" |
+| AI 生成的代码风格不一致 | 没有规范 | 提供代码规范或示例代码 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🐍 Python 虚拟环境相关</strong></summary>
+
+### 为什么要用虚拟环境？
+
+- 避免不同项目依赖冲突
+- 保持系统 Python 干净
+- 方便复现和部署
+
+### 创建和使用 .venv
+
+```bash
+# 创建虚拟环境
+python -m venv .venv
+
+# 激活虚拟环境
+# Windows
+.venv\Scripts\activate
+# macOS/Linux
+source .venv/bin/activate
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 退出虚拟环境
+deactivate
+```
+
+### 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 死活配不好环境 | 全局污染 | 删掉重来，用 `.venv` 虚拟环境隔离 |
+| `python` 命令找不到 | 没激活虚拟环境 | 先运行 `source .venv/bin/activate` |
+| 装了包但 import 报错 | 装到全局了 | 确认激活虚拟环境后再 pip install |
+| 不同项目依赖冲突 | 共用全局环境 | 每个项目单独建 `.venv` |
+| VS Code 用错 Python | 解释器没选对 | Ctrl+Shift+P → "Python: Select Interpreter" → 选 .venv |
+| pip 版本太旧 | 虚拟环境默认旧版 | `pip install --upgrade pip` |
+| requirements.txt 缺依赖 | 没导出 | `pip freeze > requirements.txt` |
+
+### 一键重置环境
+
+环境彻底乱了？删掉重来：
+
+```bash
+# 删除旧环境
+rm -rf .venv
+
+# 重新创建
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+</details>
+
+---
+
+<details open>
+<summary><strong>📦 Node.js 环境相关</strong></summary>
+
+### 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| node 版本不对 | 项目要求特定版本 | 用 nvm 管理多版本：`nvm install 18` |
+| npm install 报错 | 网络/权限问题 | 换源、清缓存、删 node_modules 重装 |
+| 全局包找不到 | PATH 没配 | `npm config get prefix` 加到 PATH |
+| package-lock 冲突 | 多人协作 | 统一用 `npm ci` 而不是 `npm install` |
+| node_modules 太大 | 正常现象 | 加到 .gitignore，不要提交 |
+
+### 常用命令
+
+```bash
+# 换淘宝源
+npm config set registry https://registry.npmmirror.com
+
+# 清缓存
+npm cache clean --force
+
+# 删除重装
+rm -rf node_modules package-lock.json
+npm install
+
+# 用 nvm 切换 Node 版本
+nvm use 18
+```
 
 </details>
 
@@ -24,11 +119,12 @@
 
 | 问题 | 原因 | 解决方案 |
 |:---|:---|:---|
-| npm install 报错 | 网络问题 | 换源：`npm config set registry https://registry.npmmirror.com` |
-| pip install 超时 | 网络问题 | 换源：`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple` |
 | 命令找不到 | 环境变量没配 | 检查 PATH，重启终端 |
-| 端口被占用 | 上次没关干净 | `lsof -i :端口号` 找到进程 kill 掉 |
+| 端口被占用 | 上次没关干净 | `lsof -i :端口号` 或 `netstat -ano \| findstr :端口号` |
 | 权限不足 | Linux/Mac 权限 | `chmod +x` 或 `sudo` |
+| 环境变量不生效 | 没 source | `source ~/.bashrc` 或重启终端 |
+| .env 文件不生效 | 没加载 | 用 `python-dotenv` 或 `dotenv` 包 |
+| Windows 路径问题 | 反斜杠 | 用 `/` 或 `\\` 或 `Path` 库 |
 
 </details>
 
@@ -41,8 +137,27 @@
 |:---|:---|:---|
 | GitHub 访问慢/超时 | 网络限制 | 配置代理，参考 [网络环境配置](../从零开始vibecoding/01-网络环境配置.md) |
 | API 调用失败 | 网络/Key 问题 | 检查代理、API Key 是否有效 |
-| 终端不走代理 | 代理配置不全 | 设置 `http_proxy` 和 `https_proxy` 环境变量 |
+| 终端不走代理 | 代理配置不全 | 设置环境变量（见下方） |
 | SSL 证书错误 | 代理/时间问题 | 检查系统时间，或临时关闭 SSL 验证 |
+| pip/npm 下载慢 | 源在国外 | 换国内镜像源 |
+| git clone 超时 | 网络限制 | 配置 git 代理或用 SSH |
+
+### 终端代理配置
+
+```bash
+# 临时设置（当前终端有效）
+export http_proxy=http://127.0.0.1:7890
+export https_proxy=http://127.0.0.1:7890
+
+# 永久设置（加到 ~/.bashrc 或 ~/.zshrc）
+echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
+echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc
+source ~/.bashrc
+
+# Git 代理
+git config --global http.proxy http://127.0.0.1:7890
+git config --global https.proxy http://127.0.0.1:7890
+```
 
 </details>
 
@@ -57,12 +172,14 @@
 | 改了代码没生效 | 缓存/没保存 | 清缓存、确认保存、重启服务 |
 | 合并代码冲突 | Git 冲突 | 让 AI 帮你解决：贴出冲突内容 |
 | 依赖版本冲突 | 版本不兼容 | 指定版本号，或用虚拟环境隔离 |
+| 中文乱码 | 编码问题 | 统一用 UTF-8，文件开头加 `# -*- coding: utf-8 -*-` |
+| 热更新不生效 | 监听问题 | 检查文件是否在监听范围内 |
 
 </details>
 
 ---
 
-<details>
+<details open>
 <summary><strong>🎯 Claude Code / Cursor 相关</strong></summary>
 
 | 问题 | 原因 | 解决方案 |
@@ -71,12 +188,14 @@
 | Cursor 补全很慢 | 网络延迟 | 检查代理配置 |
 | 额度用完了 | 免费额度有限 | 换账号或升级付费 |
 | 规则文件不生效 | 路径/格式错误 | 检查 `.cursorrules` 或 `CLAUDE.md` 位置 |
+| AI 读不到项目文件 | 工作区问题 | 确认在正确目录打开，检查 .gitignore |
+| 生成代码位置错误 | 光标位置 | 先把光标放到正确位置再生成 |
 
 </details>
 
 ---
 
-<details>
+<details open>
 <summary><strong>🚀 部署相关</strong></summary>
 
 | 问题 | 原因 | 解决方案 |
@@ -85,18 +204,271 @@
 | 构建超时 | 项目太大 | 优化依赖，增加构建时间限制 |
 | 环境变量没生效 | 没配置 | 在部署平台设置环境变量 |
 | CORS 跨域错误 | 后端没配置 | 添加 CORS 中间件 |
+| 静态文件 404 | 路径问题 | 检查 build 输出目录配置 |
+| 内存不足 | 免费套餐限制 | 优化代码或升级套餐 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🗄️ 数据库相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 连接被拒绝 | 服务没启动 | 启动数据库服务 |
+| 认证失败 | 密码错误 | 检查用户名密码，重置密码 |
+| 表不存在 | 没迁移 | 运行 migration |
+| 数据丢失 | 没持久化 | Docker 加 volume，或用云数据库 |
+| 连接数过多 | 没关连接 | 用连接池，及时关闭连接 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🐳 Docker 相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 镜像拉取失败 | 网络问题 | 配置镜像加速器 |
+| 容器启动失败 | 端口冲突/配置错误 | 检查日志 `docker logs 容器名` |
+| 文件修改不生效 | 没挂载 volume | 加 `-v` 参数挂载目录 |
+| 磁盘空间不足 | 镜像太多 | `docker system prune` 清理 |
 
 </details>
 
 ---
 
-## 💡 通用排查思路
+<details open>
+<summary><strong>🧠 大模型使用相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| Token 超限 | 输入太长 | 精简上下文，只给必要信息 |
+| 回复被截断 | 输出 token 限制 | 让 AI 分段输出，或说"继续" |
+| 不同模型结果差异大 | 模型特性不同 | 根据任务选模型：Claude 写代码，GPT 通用 |
+| 温度参数影响 | temperature 设置 | 代码生成用低温度(0-0.3)，创意用高温度 |
+| 系统提示词被忽略 | 提示词太长/冲突 | 精简系统提示词，放重要的在前面 |
+| JSON 输出格式错误 | 模型不稳定 | 用 JSON mode，或让 AI 只输出代码块 |
+| 多轮对话质量下降 | 上下文污染 | 定期开新对话，保持上下文干净 |
+| API 调用报错 429 | 频率限制 | 加延迟重试，或升级 API 套餐 |
+| 流式输出乱码 | 编码/解析问题 | 检查 SSE 解析，确保 UTF-8 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🏗️ 软件架构相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 代码越写越乱 | 没有架构设计 | 先画架构图，再写代码 |
+| 改一处坏多处 | 耦合太紧 | 拆分模块，定义清晰接口 |
+| 不知道代码放哪 | 目录结构混乱 | 参考 [通用项目架构模板](../模板与资源/通用项目架构模板.md) |
+| 重复代码太多 | 没有抽象 | 提取公共函数/组件 |
+| 状态管理混乱 | 全局状态滥用 | 用状态管理库，单向数据流 |
+| 配置散落各处 | 没有统一管理 | 集中到 config 文件或环境变量 |
+| 难以测试 | 依赖太多 | 依赖注入，mock 外部服务 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🔄 Git 版本控制相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 提交了不该提交的文件 | .gitignore 没配 | 加到 .gitignore，`git rm --cached` |
+| 提交了敏感信息 | 没检查 | 用 git-filter-branch 清理历史，换 key |
+| 合并冲突不会解决 | 不熟悉 Git | 用 VS Code 冲突解决工具，或让 AI 帮忙 |
+| commit 信息写错了 | 手滑 | `git commit --amend` 修改 |
+| 想撤销上次提交 | 提交错了 | `git reset --soft HEAD~1` |
+| 分支太多太乱 | 没有规范 | 用 Git Flow 或 trunk-based |
+| push 被拒绝 | 远程有新提交 | 先 pull --rebase 再 push |
+
+### 常用 Git 命令
+
+```bash
+# 撤销工作区修改
+git checkout -- 文件名
+
+# 撤销暂存区
+git reset HEAD 文件名
+
+# 撤销上次提交（保留修改）
+git reset --soft HEAD~1
+
+# 查看提交历史
+git log --oneline -10
+
+# 暂存当前修改
+git stash
+git stash pop
+```
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🧪 测试相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 不知道测什么 | 没有测试思维 | 测边界条件、异常情况、核心逻辑 |
+| 测试太慢 | 测试粒度太大 | 多写单元测试，少写 E2E |
+| 测试不稳定 | 依赖外部服务 | mock 外部依赖 |
+| 测试通过但线上出 bug | 覆盖不全 | 增加边界测试，用 coverage 检查 |
+| 改代码就要改测试 | 测试耦合实现 | 测试行为而非实现 |
+| AI 生成的测试没用 | 只测 happy path | 让 AI 补充边界和异常测试 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>⚡ 性能相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 页面加载慢 | 资源太大 | 压缩、懒加载、CDN |
+| API 响应慢 | 查询没优化 | 加索引、缓存、分页 |
+| 内存泄漏 | 没清理资源 | 检查事件监听、定时器、闭包 |
+| CPU 占用高 | 死循环/重复计算 | 用 profiler 定位热点 |
+| 数据库查询慢 | N+1 问题 | 用 JOIN 或批量查询 |
+| 前端卡顿 | 重渲染太多 | React.memo、useMemo、虚拟列表 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🔐 安全相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| API Key 泄露 | 提交到 Git | 用环境变量，加到 .gitignore |
+| SQL 注入 | 拼接 SQL | 用参数化查询/ORM |
+| XSS 攻击 | 没转义用户输入 | 转义 HTML，用 CSP |
+| CSRF 攻击 | 没有 token 验证 | 加 CSRF token |
+| 密码明文存储 | 安全意识不足 | 用 bcrypt 等哈希算法 |
+| 敏感信息日志 | 打印了不该打印的 | 脱敏处理，生产环境关闭 debug |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>📱 前端开发相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 样式不生效 | 优先级/缓存 | 检查选择器优先级，清缓存 |
+| 移动端适配问题 | 没做响应式 | 用 rem/vw，媒体查询 |
+| 白屏 | JS 报错 | 看控制台，加错误边界 |
+| 状态不同步 | 异步问题 | 用 useEffect 依赖，或状态管理库 |
+| 组件不更新 | 引用没变 | 返回新对象/数组，不要直接修改 |
+| 打包体积太大 | 没有优化 | 按需引入、代码分割、tree shaking |
+| 跨域问题 | 浏览器安全策略 | 后端配 CORS，或用代理 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🖥️ 后端开发相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 接口返回慢 | 同步阻塞 | 用异步，耗时任务放队列 |
+| 并发问题 | 竞态条件 | 加锁、用事务、乐观锁 |
+| 服务挂了没发现 | 没有监控 | 加健康检查、告警 |
+| 日志找不到问题 | 日志不全 | 加 request_id，结构化日志 |
+| 配置不同环境 | 硬编码 | 用环境变量区分 dev/prod |
+| OOM 崩溃 | 内存泄漏/数据太大 | 分页、流式处理、检查泄漏 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🔌 API 设计相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 接口命名混乱 | 没有规范 | 遵循 RESTful，动词用 HTTP 方法 |
+| 返回格式不统一 | 没有约定 | 统一响应结构 `{code, data, message}` |
+| 版本升级困难 | 没有版本控制 | URL 加版本号 `/api/v1/` |
+| 文档和实现不一致 | 手动维护 | 用 Swagger/OpenAPI 自动生成 |
+| 错误信息不明确 | 只返回 500 | 细分错误码，返回有用信息 |
+| 分页参数不统一 | 各写各的 | 统一用 `page/size` 或 `offset/limit` |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>📊 数据处理相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 数据格式不对 | 类型转换问题 | 做好类型校验和转换 |
+| 时区问题 | 没统一时区 | 存 UTC，显示时转本地 |
+| 精度丢失 | 浮点数问题 | 金额用整数（分），或 Decimal |
+| 大文件处理 OOM | 一次性加载 | 流式处理、分块读取 |
+| 编码问题 | 不是 UTF-8 | 统一用 UTF-8，读文件指定编码 |
+| 空值处理 | null/undefined | 做好空值判断，给默认值 |
+
+</details>
+
+---
+
+<details open>
+<summary><strong>🤝 协作相关</strong></summary>
+
+| 问题 | 原因 | 解决方案 |
+|:---|:---|:---|
+| 代码风格不统一 | 没有规范 | 用 ESLint/Prettier/Black，配置统一 |
+| PR 太大难 review | 改动太多 | 小步提交，一个 PR 一个功能 |
+| 文档过时 | 没人维护 | 代码和文档一起改，CI 检查 |
+| 不知道谁负责 | 没有 owner | 用 CODEOWNERS 文件 |
+| 重复造轮子 | 不知道有现成的 | 建立内部组件库/文档 |
+
+</details>
 
 1. **看错误信息** - 完整复制给 AI
 2. **最小复现** - 找到最简单能复现问题的代码
 3. **二分法** - 注释一半代码，定位问题范围
 4. **换环境** - 换浏览器/终端/设备试试
 5. **重启大法** - 重启服务/编辑器/电脑
+6. **删掉重来** - 环境乱了就删掉重建虚拟环境
+
+---
+
+## 🔥 终极解决方案
+
+实在搞不定？试试这个提示词：
+
+```
+我遇到了一个问题，已经尝试了很多方法都没解决。
+
+错误信息：
+[粘贴完整错误]
+
+我的环境：
+- 操作系统：
+- Python/Node 版本：
+- 相关依赖版本：
+
+我已经尝试过：
+1. xxx
+2. xxx
+
+请帮我分析可能的原因，并给出解决方案。
+```
 
 ---