charieswei
/
vibe-coding-cn
mirror of https://github.com/tukuaiai/vibe-coding-cn.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
vibe-coding-cn/documents/00-基础指南/常见坑汇总.md

15 KiB
Raw Blame History

🕳️ 常见坑汇总

Vibe Coding 过程中的常见问题和解决方案

🤖 AI 对话相关
问题 原因 解决方案
AI 生成的代码跑不起来 上下文不足 提供完整错误信息，说明运行环境
AI 反复修改同一个问题 陷入循环 换个思路描述，或开新对话
AI 幻觉，编造不存在的 API 模型知识过时 提供官方文档链接，让 AI 参考
代码越改越乱 没有规划 先让 AI 出方案，确认后再写代码
AI 不理解我的需求 描述模糊 用具体例子说明，给输入输出示例
AI 忘记之前的对话 上下文丢失 重新提供关键信息，或用 memory bank
AI 改了不该改的代码 指令不明确 明确说"只改 xxx，不要动其他文件"
AI 生成的代码风格不一致 没有规范 提供代码规范或示例代码
🐍 Python 虚拟环境相关

为什么要用虚拟环境？

  • 避免不同项目依赖冲突
  • 保持系统 Python 干净
  • 方便复现和部署

创建和使用 .venv

# 创建虚拟环境
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

一键重置环境

环境彻底乱了？删掉重来：

# 删除旧环境
rm -rf .venv

# 重新创建
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
📦 Node.js 环境相关

常见问题

问题 原因 解决方案
node 版本不对 项目要求特定版本 用 nvm 管理多版本：nvm install 18
npm install 报错 网络/权限问题 换源、清缓存、删 node_modules 重装
全局包找不到 PATH 没配 npm config get prefix 加到 PATH
package-lock 冲突 多人协作 统一用 npm ci 而不是 npm install
node_modules 太大 正常现象 加到 .gitignore，不要提交

常用命令

# 换淘宝源
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
🔧 环境配置相关
问题 原因 解决方案
命令找不到 环境变量没配 检查 PATH，重启终端
端口被占用 上次没关干净 lsof -i :端口号 或 netstat -ano | findstr :端口号
权限不足 Linux/Mac 权限 chmod +x 或 sudo
环境变量不生效 没 source source ~/.bashrc 或重启终端
.env 文件不生效 没加载 用 python-dotenv 或 dotenv 包
Windows 路径问题 反斜杠 用 / 或 \\ 或 Path 库
🌐 网络相关
问题 原因 解决方案
GitHub 访问慢/超时 网络限制 配置代理，参考 网络环境配置
API 调用失败 网络/Key 问题 检查代理、API Key 是否有效
终端不走代理 代理配置不全 设置环境变量（见下方）
SSL 证书错误 代理/时间问题 检查系统时间，或临时关闭 SSL 验证
pip/npm 下载慢 源在国外 换国内镜像源
git clone 超时 网络限制 配置 git 代理或用 SSH

终端代理配置

# 临时设置（当前终端有效）
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
📝 代码相关
问题 原因 解决方案
代码文件太大，AI 处理不了 超出上下文 拆分文件，只给 AI 相关部分
改了代码没生效 缓存/没保存 清缓存、确认保存、重启服务
合并代码冲突 Git 冲突 让 AI 帮你解决：贴出冲突内容
依赖版本冲突 版本不兼容 指定版本号，或用虚拟环境隔离
中文乱码 编码问题 统一用 UTF-8，文件开头加 # -*- coding: utf-8 -*-
热更新不生效 监听问题 检查文件是否在监听范围内
🎯 Claude Code / Cursor 相关
问题 原因 解决方案
Claude Code 连不上 网络/认证 检查代理，重新 claude login
Cursor 补全很慢 网络延迟 检查代理配置
额度用完了 免费额度有限 换账号或升级付费
规则文件不生效 路径/格式错误 检查 .cursorrules 或 CLAUDE.md 位置
AI 读不到项目文件 工作区问题 确认在正确目录打开，检查 .gitignore
生成代码位置错误 光标位置 先把光标放到正确位置再生成
🚀 部署相关
问题 原因 解决方案
本地能跑，部署失败 环境差异 检查 Node/Python 版本，环境变量
构建超时 项目太大 优化依赖，增加构建时间限制
环境变量没生效 没配置 在部署平台设置环境变量
CORS 跨域错误 后端没配置 添加 CORS 中间件
静态文件 404 路径问题 检查 build 输出目录配置
内存不足 免费套餐限制 优化代码或升级套餐
🗄️ 数据库相关
问题 原因 解决方案
连接被拒绝 服务没启动 启动数据库服务
认证失败 密码错误 检查用户名密码，重置密码
表不存在 没迁移 运行 migration
数据丢失 没持久化 Docker 加 volume，或用云数据库
连接数过多 没关连接 用连接池，及时关闭连接
🐳 Docker 相关
问题 原因 解决方案
镜像拉取失败 网络问题 配置镜像加速器
容器启动失败 端口冲突/配置错误 检查日志 docker logs 容器名
文件修改不生效 没挂载 volume 加 -v 参数挂载目录
磁盘空间不足 镜像太多 docker system prune 清理
🧠 大模型使用相关
问题 原因 解决方案
Token 超限 输入太长 精简上下文，只给必要信息
回复被截断 输出 token 限制 让 AI 分段输出，或说"继续"
不同模型结果差异大 模型特性不同 根据任务选模型：Claude 写代码，GPT 通用
温度参数影响 temperature 设置 代码生成用低温度(0-0.3)，创意用高温度
系统提示词被忽略 提示词太长/冲突 精简系统提示词，放重要的在前面
JSON 输出格式错误 模型不稳定 用 JSON mode，或让 AI 只输出代码块
多轮对话质量下降 上下文污染 定期开新对话，保持上下文干净
API 调用报错 429 频率限制 加延迟重试，或升级 API 套餐
流式输出乱码 编码/解析问题 检查 SSE 解析，确保 UTF-8
🏗️ 软件架构相关
问题 原因 解决方案
代码越写越乱 没有架构设计 先画架构图，再写代码
改一处坏多处 耦合太紧 拆分模块，定义清晰接口
不知道代码放哪 目录结构混乱 参考 通用项目架构模板
重复代码太多 没有抽象 提取公共函数/组件
状态管理混乱 全局状态滥用 用状态管理库，单向数据流
配置散落各处 没有统一管理 集中到 config 文件或环境变量
难以测试 依赖太多 依赖注入，mock 外部服务
🔄 Git 版本控制相关
问题 原因 解决方案
提交了不该提交的文件 .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 命令

# 撤销工作区修改
git checkout -- 文件名

# 撤销暂存区
git reset HEAD 文件名

# 撤销上次提交（保留修改）
git reset --soft HEAD~1

# 查看提交历史
git log --oneline -10

# 暂存当前修改
git stash
git stash pop
🧪 测试相关
问题 原因 解决方案
不知道测什么 没有测试思维 测边界条件、异常情况、核心逻辑
测试太慢 测试粒度太大 多写单元测试，少写 E2E
测试不稳定 依赖外部服务 mock 外部依赖
测试通过但线上出 bug 覆盖不全 增加边界测试，用 coverage 检查
改代码就要改测试 测试耦合实现 测试行为而非实现
AI 生成的测试没用 只测 happy path 让 AI 补充边界和异常测试
⚡ 性能相关
问题 原因 解决方案
页面加载慢 资源太大 压缩、懒加载、CDN
API 响应慢 查询没优化 加索引、缓存、分页
内存泄漏 没清理资源 检查事件监听、定时器、闭包
CPU 占用高 死循环/重复计算 用 profiler 定位热点
数据库查询慢 N+1 问题 用 JOIN 或批量查询
前端卡顿 重渲染太多 React.memo、useMemo、虚拟列表
🔐 安全相关
问题 原因 解决方案
API Key 泄露 提交到 Git 用环境变量，加到 .gitignore
SQL 注入 拼接 SQL 用参数化查询/ORM
XSS 攻击 没转义用户输入 转义 HTML，用 CSP
CSRF 攻击 没有 token 验证 加 CSRF token
密码明文存储 安全意识不足 用 bcrypt 等哈希算法
敏感信息日志 打印了不该打印的 脱敏处理，生产环境关闭 debug
📱 前端开发相关
问题 原因 解决方案
样式不生效 优先级/缓存 检查选择器优先级，清缓存
移动端适配问题 没做响应式 用 rem/vw，媒体查询
白屏 JS 报错 看控制台，加错误边界
状态不同步 异步问题 用 useEffect 依赖，或状态管理库
组件不更新 引用没变 返回新对象/数组，不要直接修改
打包体积太大 没有优化 按需引入、代码分割、tree shaking
跨域问题 浏览器安全策略 后端配 CORS，或用代理
🖥️ 后端开发相关
问题 原因 解决方案
接口返回慢 同步阻塞 用异步，耗时任务放队列
并发问题 竞态条件 加锁、用事务、乐观锁
服务挂了没发现 没有监控 加健康检查、告警
日志找不到问题 日志不全 加 request_id，结构化日志
配置不同环境 硬编码 用环境变量区分 dev/prod
OOM 崩溃 内存泄漏/数据太大 分页、流式处理、检查泄漏
🔌 API 设计相关
问题 原因 解决方案
接口命名混乱 没有规范 遵循 RESTful，动词用 HTTP 方法
返回格式不统一 没有约定 统一响应结构 {code, data, message}
版本升级困难 没有版本控制 URL 加版本号 /api/v1/
文档和实现不一致 手动维护 用 Swagger/OpenAPI 自动生成
错误信息不明确 只返回 500 细分错误码，返回有用信息
分页参数不统一 各写各的 统一用 page/size 或 offset/limit
📊 数据处理相关
问题 原因 解决方案
数据格式不对 类型转换问题 做好类型校验和转换
时区问题 没统一时区 存 UTC，显示时转本地
精度丢失 浮点数问题 金额用整数（分），或 Decimal
大文件处理 OOM 一次性加载 流式处理、分块读取
编码问题 不是 UTF-8 统一用 UTF-8，读文件指定编码
空值处理 null/undefined 做好空值判断，给默认值
🤝 协作相关
问题 原因 解决方案
代码风格不统一 没有规范 用 ESLint/Prettier/Black，配置统一
PR 太大难 review 改动太多 小步提交，一个 PR 一个功能
文档过时 没人维护 代码和文档一起改，CI 检查
不知道谁负责 没有 owner 用 CODEOWNERS 文件
重复造轮子 不知道有现成的 建立内部组件库/文档
  1. 看错误信息 - 完整复制给 AI
  2. 最小复现 - 找到最简单能复现问题的代码
  3. 二分法 - 注释一半代码，定位问题范围
  4. 换环境 - 换浏览器/终端/设备试试
  5. 重启大法 - 重启服务/编辑器/电脑
  6. 删掉重来 - 环境乱了就删掉重建虚拟环境

🔥 终极解决方案

实在搞不定？试试这个提示词：

我遇到了一个问题，已经尝试了很多方法都没解决。

错误信息：
[粘贴完整错误]

我的环境：
- 操作系统：
- Python/Node 版本：
- 相关依赖版本：

我已经尝试过：
1. xxx
2. xxx

请帮我分析可能的原因，并给出解决方案。

📝 贡献

遇到新坑？欢迎 PR 补充！