头条【vue+fastapi 】全栈教学项目系列之《02_双系统零基础环境搭建手册》

碧水澜庭2026-08-12 9:37

本文是头条【vue+fastapi 】全栈教学项目系列之《双系统零基础环境搭建手册》
📎 配套开源项目（均已开源，欢迎 Star / Fork）：

🛠️ 双系统零基础环境搭建手册

适用系统：Windows 10/11 + macOS 12+

严格版本锁定：所有软件版本均已验证兼容性

零跳跃承诺：每一步都有截图描述和验证方法

📋 环境需求总览

必须安装的软件清单

序号 软件名称 用途 Windows版本 macOS版本 内存占用
1 Node.js 前端运行环境 v18.20.3 LTS v18.20.3 LTS ~200MB
2 Python 后端运行环境 3.11.9 3.11.9 ~100MB
3 MySQL 数据库服务器 8.0.38 8.0.38 ~500MB
4 Redis 缓存服务器 7.2.5 7.2.5 ~50MB
5 VS Code 代码编辑器 最新版 最新版 ~400MB
6 Git 版本控制 2.45.2 2.45.2 ~50MB

💡 IDE 选择说明（重要）

本教程统一用 VS Code 演示「前端 + 后端」一套环境（装 Volar 插件写 Vue、装 Python 扩展写后端）。

但需要明确一个行业事实：目前主流的后端 Python 类开发项目（如 Django、FastAPI、Flask），最常用的 IDE 是 PyCharm（JetBrains 出品）。

  • PyCharm 专业版：功能最全，内置数据库工具、Django/FastAPI 模板与代码洞察、远程开发、单元测试 UI，是后端 Python 团队的主流选择。
  • PyCharm 社区版：免费开源，满足日常 Python 后端开发（缺少数据库工具、远程开发等高级功能）。
  • 如果你主要做后端 Python 开发，强烈推荐使用 PyCharm；本教程之所以用 VS Code，是为了「一套编辑器同时覆盖前后端」，二者都能正常开发，不影响学习进度。

电脑配置要求

配置项 最低要求 推荐配置
操作系统 Windows 10 / macOS 12 Windows 11 / macOS 14
内存（RAM） 8GB 16GB或以上
硬盘空间 10GB可用空间 SSD固态硬盘
处理器 双核 四核及以上
网络 能联网下载软件 稳定的网络连接

💡 如果你的电脑比较旧：关闭其他程序，只留VS Code和浏览器，也能流畅开发

🪟 Windows 系统安装指南

第一步：安装 Node.js（前端必需）

1.1 下载安装包

  1. 打开浏览器，访问官网下载页面：

    复制代码 
    https://nodejs.org/en/download

  2. 点击 Windows Installer (.msi) 64位版本（LTS长期支持版）

    LTS = Long Term Support（长期支持版），更稳定，适合初学者

1.2 执行安装
  1. 双击下载的 .msi 安装文件
  2. 点击 Next（下一步）
  3. 勾选 I accept the agreement（接受协议），点击 Next
  4. 保持默认安装路径 C:\Program Files\nodejs\，点击 Next
  5. 保持默认组件全选，点击 Next
  6. 点击 Install（安装）
  7. 等待进度条走完，点击 Finish（完成）
1.3 验证安装成功
  1. 按 Win + R 键，输入 cmd，回车打开命令提示符
  2. 依次输入以下命令：
bash 复制代码 
# 检查Node.js版本
node -v

# 应该显示：v18.20.3 或类似版本号

# 检查npm版本（npm是Node.js的包管理器）
npm -v

# 应该显示：10.x.x 或类似版本号

✅ 验证通过标志：两个命令都能显示版本号，不报错

1.4 配置npm镜像源（国内必做）
bash 复制代码 
# 设置淘宝镜像源（加速下载）
npm config set registry https://registry.npmmirror.com

# 验证是否设置成功
npm config get registry

# 应该显示：https://registry.npmmirror.com

为什么要这样做？ npm默认从国外服务器下载，速度很慢。淘宝镜像在国内有副本，速度快10倍以上。

第二步：安装 Python（后端必需）

2.1 下载安装包

  1. 访问Python官网：

    复制代码 
    https://www.python.org/downloads/release/python-3119/

  2. 向下滚动，找到 Files 区域

  3. 点击 Windows installer (64-bit) 下载

    ⚠️ 注意：一定要选64位版本，除非你的电脑是非常老的32位系统

2.2 执行安装（关键步骤！）

  1. 双击下载的 .exe 安装文件

  2. ⭐ 最重要的一步 ：勾选 Add Python to PATH（添加到环境变量）

    !勾选位置示意

    在窗口底部有个复选框 Add python.exe to PATH ，务必勾选它！

  3. 点击 Install Now（立即安装）

  4. 等待安装完成，点击 Disable path length limit（禁用路径长度限制）

  5. 点击 Close（关闭）

2.3 验证安装成功
  1. 关闭之前打开的cmd窗口，重新打开一个新的cmd
  2. 输入以下命令：
bash 复制代码 
# 检查Python版本
python --version

# 或者也可以用
python3 --version

# 应该显示：Python 3.11.9 或类似版本

# 检查pip版本（pip是Python的包管理器）
pip --version

# 应该显示：pip 24.x.x 来自 Python 3.11

✅ 验证通过标志：显示Python 3.11.x版本号

❌ 如果提示"不是内部命令"：

  • 说明没勾选"Add to PATH"，需要重新安装，这次记得勾选
2.4 配置pip镜像源（国内必做）
bash 复制代码 
# 创建pip配置文件夹
mkdir %APPDATA%\pip

# 创建配置文件（直接复制这段命令执行）
echo [global] > %APPDATA%\pip\pip.ini
echo index-url=https://mirrors.aliyun.com/pypi/simple/ >> %APPDATA%\pip\pip.ini
echo trusted-host=mirrors.aliyun.com >> %APPDATA%\pip\pip.ini

# 验证配置文件内容
type %APPDATA%\pip\pip.ini

应该显示：

ini 复制代码 
[global]
index-url=https://mirrors.aliyun.com/pypi/simple/
trusted-host=mirrors.aliyun.com

第三步：安装 MySQL（数据库）

3.1 下载安装包

  1. 访问MySQL官网下载页：

    复制代码 
    https://dev.mysql.com/downloads/installer/

  2. 点击 Looking for previous GA versions? 链接

  3. 选择 Windows (x86, 32 & 64-bit), MSI Installer（第二个，大的那个，约300MB+）

小的那个是在线安装器，网速慢会很痛苦。大的那个是离线完整包。

3.2 执行安装
  1. 双击下载的 .msi 安装文件
  2. 选择 Server only（仅服务器），点击 Execute
  3. 点击 Execute（执行） 安装必要组件
  4. 点击 Next（下一步）
  5. 配置设置（重要） ：
    • Type and Networking：保持默认，点击 Next
    • Authentication Method ：选择第一个 Use Strong Password Encryption
    • Accounts and Roles ：
      • 设置Root密码：123456（记住这个密码！）
      • 勾选 Configure MySQL Server as a Windows Service
  6. 点击 Execute（执行） 完成配置
  7. 点击 Finish（完成）
3.3 验证安装成功

方法A：使用命令行

  1. 打开cmd，输入：
bash 复制代码 
mysql -u root -p

  1. 输入密码 123456

  2. 看到 mysql> 提示符就成功了！

  3. 输入 exit 退出

方法B：检查服务是否运行

  1. 按 Win + R，输入 services.msc，回车
  2. 找到 MySQL 服务
  3. 状态显示为"正在运行"即成功
3.4 创建项目数据库
sql 复制代码 
-- 登录MySQL后，依次执行以下命令：

-- 1. 创建数据库（用于我们的头条项目）
CREATE DATABASE toutiao_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 2. 查看是否创建成功
SHOW DATABASES;

-- 应该能看到 toutiao_db 这个数据库

-- 3. 退出
exit;

第四步：安装 Redis（缓存）

4.1 下载安装包

  1. 访问GitHub releases页面：

    复制代码 
    https://github.com/tporadowski/redis/releases

  2. 找到最新版本的 Redis-x64-*.msi 文件下载

4.2 执行安装
  1. 双击 .msi 文件
  2. 一路点击 Next（下一步）
  3. 保持默认端口 6379，点击 Next
  4. 勾选 Add to PATH，点击 Next
  5. 点击 Install（安装）
  6. 点击 Finish（完成）
4.3 验证安装成功
  1. 打开新的cmd窗口，输入：
bash 复制代码 
redis-cli ping

# 应该返回：PONG

✅ 验证通过标志 ：返回 PONG

第五步：安装 VS Code（代码编辑器）

📌 关于 IDE ：本教程统一用 VS Code 演示「前端 + 后端」。若你主要做后端 Python 开发，业界更主流的 IDE 是 PyCharm（专业版 / 社区版）------它对 Django、FastAPI 的支持比 VS Code 更完整。VS Code 在此处同样可以写 Python，按下面步骤装好即可。

5.1 下载安装

  1. 访问官网：

    复制代码 
    https://code.visualstudio.com/

  2. 点击 Download for Windows 下载

  3. 双击安装文件，一路 Next 安装完成

5.2 安装必备插件
  1. 打开 VS Code
  2. 点击左侧扩展图标（四个方块）或按 Ctrl + Shift + X
  3. 搜索并安装以下插件：
插件名称 用途 搜索关键词
Chinese (Simplified) 中文界面 Chinese
Volar Vue 3语法支持 Volar
Python Python开发支持 Python
ESLint 代码规范检查 ESLint
Prettier - Code formatter 代码格式化 Prettier

第六步：安装 Git（版本控制）

6.1 下载安装

  1. 访问官网：

    复制代码 
    https://git-scm.com/download/win

  2. 下载后双击安装

  3. 一路默认选项，点击 Next 直到完成

6.2 验证安装
bash 复制代码 
# 在cmd中输入
git --version

# 应该显示：git version 2.45.2 或类似版本

🍎 macOS 系统安装指南

第一步：安装 Homebrew（包管理器）

Homebrew 是macOS上的软件包管理器，类似iPhone的App Store。

1.1 打开终端
  1. 按 Command + 空格，输入 Terminal，回车打开终端
  2. 或者从 启动台 → 其他 →终端 打开
1.2 安装 Homebrew

在终端中粘贴以下命令，然后回车：

bash 复制代码 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⚠️ 会要求输入电脑密码（输入时不会显示字符，这是正常的），输完按回车

1.3 验证安装
bash 复制代码 
brew --version

# 应该显示：Homebrew 4.x.x 版本信息

第二步：安装 Node.js

bash 复制代码 
# 使用Homebrew安装Node.js
brew install node@18

# 验证安装
node -v
# 显示：v18.20.x

npm -v
# 显示：10.x.x

# 配置淘宝镜像源
npm config set registry https://registry.npmmirror.com

第三步：安装 Python

macOS自带Python，但版本可能不合适。我们安装最新的Python 3.11：

bash 复制代码 
# 使用Homebrew安装Python
brew install python@3.11

# 验证安装
python3 --version
# 显示：Python 3.11.x

pip3 --version
# 显示：pip 24.x.x

# 配置阿里云镜像源
pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip3 config set global.trusted-host mirrors.aliyun.com

第四步：安装 MySQL

bash 复制代码 
# 使用Homebrew安装MySQL
brew install mysql@8.0

# 启动MySQL服务
brew services start mysql@8.0

# 初始化安全配置（设置root密码）
mysql_secure_installation

# 按照提示操作：
# 1. 是否启用密码验证策略？选 n（简化操作）
# 2. 设置root密码：输入 123456
# 3. 后续问题都选 y（删除匿名用户、禁止远程root登录等）

# 验证安装
mysql -u root -p
# 输入密码 123456，看到 mysql> 提示符即成功

# 创建项目数据库
CREATE DATABASE toutiao_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 退出
exit;

第五步：安装 Redis

bash 复制代码 
# 使用Homebrew安装Redis
brew install redis

# 启动Redis服务
brew services start redis

# 验证安装
redis-cli ping
# 返回 PONG 即成功

第六步：安装 VS Code

📌 关于 IDE ：本教程统一用 VS Code 演示「前端 + 后端」。若你主要做后端 Python 开发，业界主流 IDE 是 PyCharm（专业版 / 社区版）。VS Code 也能写 Python，按下面步骤安装即可。

bash 复制代码 
# 使用Homebrew安装VS Code
brew install --cask visual-studio-code

或者手动安装：

  1. 访问 https://code.visualstudio.com/
  2. 点击 Download for Mac
  3. 下载后拖到 Applications 文件夹

安装插件（同Windows部分第五步）

第七步：安装 Git

macOS可能已经预装了Git，检查一下：

bash 复制代码 
git --version

# 如果显示版本号就不用安装了
# 如果提示命令不存在，执行：
brew install git

✅ 环境校验清单（必做！）

完成所有安装后，请逐项检查：

Windows 用户检查清单

打开 CMD 或 PowerShell，依次执行：

bash 复制代码 
# ===== 第1项：Node.js =====
node -v
# 期望输出：v18.20.x ✓

# ===== 第2项：npm =====
npm -v
# 期望输出：10.x.x ✓

# ===== 第3项：Python =====
python --version
# 期望输出：Python 3.11.x ✓

# ===== 第4项：pip =====
pip --version
# 期望输出：pip 24.x.x from ... ✓

# ===== 第5项：MySQL =====
mysql -u root -p123456 -e "SELECT 1"
# 期望输出：显示数字1（无报错）✓

# ===== 第6项：Redis =====
redis-cli ping
# 期望输出：PONG ✓

# ===== 第7项：Git =====
git --version
# 期望输出：git version 2.45.x ✓

# ===== 第8项：VS Code =====
code --version
# 期望输出：显示VS Code版本信息 ✓

macOS 用户检查清单

打开 终端，依次执行：

bash 复制代码 
# ===== 第1项：Node.js =====
node -v
# 期望输出：v18.20.x ✓

# ===== 第2项：npm =====
npm -v
# 期望输出：10.x.x ✓

# ===== 第3项：Python =====
python3 --version
# 期望输出：Python 3.11.x ✓

# ===== 第4项：pip =====
pip3 --version
# 期望输出：pip 24.x.x ✓

# ===== 第5项：MySQL =====
mysql -u root -p123456 -e "SELECT 1"
# 期望输出：显示数字1 ✓

# ===== 第6项：Redis =====
redis-cli ping
# 期望输出：PONG ✓

# ===== 第7项：Git =====
git --version
# 期望输出：git version 2.45.x ✓

# ===== 第8项：VS Code =====
code --version
# 期望输出：显示版本信息 ✓

校验结果记录表

序号 软件 版本号 状态 备注
1 Node.js ________ ☐通过
2 npm ________ ☐通过
3 Python ________ ☐通过
4 pip ________ ☐通过
5 MySQL 8.0.x ☐通过 root密码：______
6 Redis 7.x ☐通过
7 Git ________ ☐通过
8 VS Code 最新版 ☐通过

✅ 全部通过：恭喜！环境搭建完成，可以开始下一步了！

❌ 有未通过的：查看下面的「常见问题」章节

🚨 常见问题与解决方案

问题1：node -v 提示"不是内部或外部命令"

原因：安装时环境变量没生效

解决方案（Windows）：

  1. 重启电脑（最简单）
  2. 或者：右键此电脑 → 属性 → 高级系统设置 → 环境变量 → 在Path中添加 C:\Program Files\nodejs\

解决方案（macOS）：

bash 复制代码 
# 重新打开终端再试
# 如果还不行，执行：
export PATH="/opt/homebrew/bin:$PATH"

问题2：python --version 提示找不到命令

原因：Windows安装时没勾选 "Add to PATH"

解决方案：

  1. 卸载Python（控制面板 → 程序 → Python → 卸载）
  2. 重新下载安装包
  3. 这次一定勾选 Add Python to PATH！
  4. 安装完成后重启cmd窗口再验证

问题3：MySQL连接失败 Can't connect to MySQL server

原因：MySQL服务没有启动

解决方案（Windows）：

  1. Win + R → 输入 services.msc → 回车
  2. 找到 MySQL 服务
  3. 右键 → 启动

解决方案（macOS）：

bash 复制代码 
brew services start mysql@8.0

问题4：Redis连接失败 Could not connect

原因：Redis服务没有启动

解决方案（Windows）：

  1. Win + R → 输入 services.msc → 回车
  2. 找到 Redis 服务
  3. 右键 → 启动

解决方案（macOS）：

bash 复制代码 
brew services start redis

问题5：pip安装包很慢或超时

原因：默认从国外源下载，网络不稳定

解决方案：确保已配置国内镜像源（见前面安装步骤）

临时使用镜像源：

bash 复制代码 
pip install 包名 -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

问题6：npm install 报错 ERR!

原因：网络问题或缓存损坏

解决方案：

bash 复制代码 
# 清除npm缓存
npm cache clean --force

# 删除node_modules重新安装
rm -rf node_modules
npm install

# 如果还报错，尝试：
npm install --legacy-peer-deps

问题7：端口被占用 Address already in use

原因：之前的程序没有完全关闭

解决方案（Windows）：

bash 复制代码 
# 查看8000端口谁在占用
netstat -ano | findstr :8000

# 结束进程（PID换成上面查到的数字）
taskkill /PID 进程号 /F

解决方案（macOS）：

bash 复制代码 
# 查看8000端口占用
lsof -i :8000

# 结束进程
kill -9 PID

问题8：MySQL忘记root密码了

解决方案（Windows）：

  1. 停止MySQL服务
  2. 以跳过权限方式启动MySQL
  3. 修改密码
  4. 正常重启

具体步骤较复杂，建议直接重装MySQL，这次记住密码！

问题9：磁盘空间不足

解决方案：

  1. 清空回收站
  2. 清理npm缓存：npm cache clean --force
  3. 清理pip缓存：pip cache purge
  4. 卸载不用的软件
  5. 至少保留15GB空闲空间

问题10：杀毒软件拦截安装

原因：某些杀毒软件会误报开发工具

解决方案：

  1. 安装时暂时关闭实时防护
  2. 将开发目录添加到白名单
  3. 信任安装程序

📝 环境配置文件说明

项目中有一些配置文件需要了解：

后端 .env 文件位置

复制代码 
toutiao_backend/.env

文件内容模板（稍后在项目中创建）：

env 复制代码 
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=toutiao_db

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# OpenAI配置（可选）
OPENAI_API_KEY=your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1

⚠️ 安全提醒 ：.env 文件包含敏感信息，不要上传到GitHub！

🎯 下一步

✅ 环境搭建全部完成！

接下来请打开 《03_分阶段分步实操指引》，我们开始正式写代码！

快速跳转检查清单

  • Node.js v18+ 安装成功 ✓
  • Python 3.11+ 安装成功 ✓
  • MySQL 8.0 安装并启动 ✓
  • Redis 7.x 安装并启动 ✓
  • VS Code 及插件安装完成 ✓
  • Git 安装成功 ✓
  • toutiao_db 数据库已创建 ✓
  • 所有校验命令通过 ✓

文档版本 ：v1.0

更新日期 ：2026年7月

适用项目：toutiao_heima 新闻头条全栈项目

相关推荐
卷无止境1 天前
FastAPI中间件全解析：请求处理链条上的隐形关卡
后端·python·fastapi
卷无止境1 天前
聊聊Web开发里的流式数据 从原理到FastAPI实战
后端·python·fastapi
DsirNg2 天前
从 `@wheel.prevent.stop` 到事件捕获：一次讲清浏览器事件流与 Vue 事件修饰符
javascript·vue·事件修饰符·事件冒泡·dom 事件·事件捕获·wheel
其美杰布-富贵-李2 天前
Vue 3 模板语法速通：彻底理解 `:`、`@`、`#`、`v-if`、`v-for` 与 `v-model`
vue
爱音乐的marlon3 天前
FastAPI 学习笔记03｜core 核心层：config 是总控制台，database 是整个工程的地基
笔记·学习·fastapi
DsirNg3 天前
基于拓扑排序的画布自动布局：用最长上游路径决定节点列级
vue·流程图·拓扑排序·状态管理·有向图·自动布局·最长路径
花酒锄作田3 天前
Repository 模式在 FastAPI 中的应用
python·fastapi
喜欢的名字被抢了3 天前
FastAPI 接口安全与工程化 JWT、测试和配置管理
安全·fastapi
Maiko Star4 天前
从零落地「AI掘金头条」新闻模块：FastAPI + SQLAlchemy 异步实战
python·fastapi
热门推荐
01VSCode+CodeX扩展，无法启动02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06如何新建文件夹？ 电脑新建文件夹的4种方法072026年8月4日科技热点深度解析：AI大模型群雄逐鹿、卫星互联网组网提速、半导体封装材料革命08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09历年考研数学一、数学二、数学三真题试卷及答案PDF10Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费