安装问题

安装问题

本文档收集了 Tiebo 项目安装和设置过程中常见的问题和解决方案。

环境要求

系统要求

• Node.js: 版本 18.0.0 或更高
• npm: 版本 8.0.0 或更高
• 操作系统: Windows 10+, macOS 10.15+, 或 Linux

检查版本

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

常见问题

Q: Node.js 版本过低

问题: 运行项目时提示 “Node.js version is too low”

解决方案:

1. 访问 Node.js 官网 下载最新 LTS 版本
2. 使用版本管理工具升级：

   # 使用 nvm (推荐)
   nvm install 18
   nvm use 18
   
   # 使用 n
   n 18

Q: npm install 失败

问题: 运行 npm install 时出现错误

解决方案:

1. 清除 npm 缓存：

   npm cache clean --force

2. 删除 node_modules 和 package-lock.json：

   rm -rf node_modules package-lock.json
   npm install

3. 使用不同的 registry：

   npm install --registry https://registry.npmmirror.com

Q: 依赖冲突

问题: 出现 “peer dependency” 或版本冲突错误

解决方案:

1. 使用 --force 或 --legacy-peer-deps：

   npm install --legacy-peer-deps

2. 检查并更新依赖：

   npm outdated
   npm update

Q: 权限问题 (Linux/macOS)

问题: 安装时出现 EACCES 或权限错误

解决方案:

1. 修改 npm 全局目录权限：

   sudo chown -R $(whoami) ~/.npm

2. 使用 nvm 管理 Node.js 版本（推荐）

Q: 端口占用

问题: 启动开发服务器时提示端口已被占用

解决方案:

1. 查找占用端口的进程：

   # macOS/Linux
   lsof -i :4321
   
   # Windows
   netstat -ano | findstr :4321

2. 终止进程或使用其他端口：

   npm run dev -- --port 3000

包管理器问题

Yarn 用户

如果使用 Yarn 而不是 npm：

# 安装依赖
yarn install

# 启动开发服务器
yarn dev

# 构建项目
yarn build

pnpm 用户

如果使用 pnpm：

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建项目
pnpm build

特定环境问题

Windows 系统

问题: PowerShell 执行策略限制

解决方案:

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

问题: 路径长度限制

解决方案:

1. 启用长路径支持
2. 将项目放在较短的路径中

macOS 系统

问题: Xcode 命令行工具缺失

解决方案:

xcode-select --install

问题: 权限问题

解决方案:

# 修复文件权限
chmod -R 755 .

Linux 系统

问题: 缺少构建工具

解决方案 (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential

解决方案 (CentOS/RHEL):

sudo yum groupinstall "Development Tools"

验证安装

安装完成后，运行以下命令验证：

# 启动开发服务器
npm run dev

# 检查构建是否正常
npm run build

# 预览构建结果
npm run preview

获取帮助

如果问题仍然存在：

1. 查看错误日志: 仔细阅读错误信息，通常包含有用的线索
2. 搜索已知问题: 在 GitHub Issues 中搜索类似问题
3. 提供环境信息: 报告问题时包含操作系统、Node.js 版本等信息
4. 尝试最小重现: 创建一个新的最小项目来隔离问题

性能优化

加速安装

1. 使用国内镜像:

   npm config set registry https://registry.npmmirror.com

2. 启用并行安装:

   npm install --prefer-offline --no-audit

3. 使用 pnpm (更快的包管理器):

   npm install -g pnpm
   pnpm install

通过以上解决方案，大部分安装问题都可以得到解决。如果仍然遇到问题，请查看具体的错误信息或寻求社区帮助。