hello-agents/Additional-Chapter/NODEJS_INSTALL_GUIDE.md

Node.js 和 npx 安装教程

📋 目录

• 为什么需要安装 Node.js？
• Windows 安装教程
• macOS 安装教程
• Linux 安装教程
• 验证安装
• 常见问题

---

为什么需要安装 Node.js？

在第十章的MCP协议学习中，我们需要使用社区提供的MCP服务器，这些服务器大多数是用JavaScript/TypeScript编写的，需要Node.js运行环境。

安装Node.js后你将获得：

• ✅ node: JavaScript运行时
• ✅ npm: Node包管理器（Node Package Manager）
• ✅ npx: npm包执行器（自动下载并运行npm包）

npx的作用：

# 传统方式：需要先安装再运行
npm install -g @modelcontextprotocol/server-filesystem
server-filesystem

# 使用npx：自动下载并运行（推荐）
npx @modelcontextprotocol/server-filesystem

---

Windows 安装教程

方式1：官方安装包（推荐）

步骤1：下载安装包

访问Node.js官网：https://nodejs.org/

你会看到两个版本：

• LTS（长期支持版）：推荐大多数用户使用 ✅
• Current（最新版）：包含最新特性

推荐下载LTS版本（例如：20.x.x LTS）

步骤2：运行安装程序

1. 双击下载的 .msi 文件
2. 点击 "Next" 开始安装
3. 接受许可协议
4. 选择安装路径（默认即可）
5. 重要：确保勾选以下选项：
   • ✅ Node.js runtime
   • ✅ npm package manager
   • ✅ Add to PATH（自动添加到环境变量）
6. 点击 "Install" 开始安装
7. 等待安装完成，点击 "Finish"

步骤3：验证安装

打开 PowerShell 或 命令提示符（CMD），输入：

# 检查Node.js版本
node -v
# 应该显示：v20.x.x

# 检查npm版本
npm -v
# 应该显示：10.x.x

# 检查npx版本
npx -v
# 应该显示：10.x.x

如果都能正常显示版本号，说明安装成功！✅

---

macOS 安装教程

方式1：官方安装包

步骤1：下载安装包

访问：https://nodejs.org/

下载 LTS版本 的 .pkg 文件

步骤2：安装

1. 双击 .pkg 文件
2. 按照安装向导提示操作
3. 输入管理员密码
4. 完成安装

步骤3：验证安装

打开 终端（Terminal），输入：

node -v
npm -v
npx -v

---

Linux 安装教程

Ubuntu/Debian

方式1：使用NodeSource仓库（推荐）

# 更新包列表
sudo apt update

# 安装curl（如果还没有）
sudo apt install -y curl

# 添加NodeSource仓库（Node.js 20.x LTS）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装Node.js和npm
sudo apt install -y nodejs

# 验证安装
node -v
npm -v
npx -v

方式2：使用apt（版本可能较旧）

sudo apt update
sudo apt install -y nodejs npm

---

CentOS/RHEL/Fedora

# 添加NodeSource仓库
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -

# 安装Node.js
sudo yum install -y nodejs

# 验证安装
node -v
npm -v
npx -v

---

Arch Linux

# 使用pacman安装
sudo pacman -S nodejs npm

# 验证安装
node -v
npm -v
npx -v

---

验证安装

完整验证步骤

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

# 1. 检查版本
node -v
npm -v
npx -v

# 2. 测试Node.js
node -e "console.log('Node.js 工作正常！')"

# 3. 测试npm
npm --version

# 4. 测试npx（运行一个简单的包）
npx cowsay "Hello MCP!"

预期输出

v20.11.0
10.2.4
10.2.4
Node.js 工作正常！
10.2.4
 _____________
< Hello MCP! >
 -------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

---

测试MCP服务器连接

安装完成后，测试连接到社区MCP服务器：

测试文件系统服务器

# 使用npx运行文件系统MCP服务器
npx -y @modelcontextprotocol/server-filesystem .

如果看到服务器启动信息，说明一切正常！

在Python中测试

创建测试脚本 test_mcp.py：

import asyncio
from hello_agents.protocols import MCPClient

async def test():
    client = MCPClient([
        "npx", "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
    ])
    
    async with client:
        tools = await client.list_tools()
        print(f"✅ 成功连接！可用工具: {[t['name'] for t in tools]}")

asyncio.run(test())

运行：

python test_mcp.py

---

常见问题

Q1: 安装后命令找不到

Windows:

# 检查环境变量
echo $env:PATH

# 手动添加Node.js到PATH
# 1. 右键"此电脑" -> "属性"
# 2. "高级系统设置" -> "环境变量"
# 3. 在"系统变量"中找到"Path"
# 4. 添加：C:\Program Files\nodejs\

macOS/Linux:

# 检查环境变量
echo $PATH

# 添加到~/.bashrc 或 ~/.zshrc
export PATH="/usr/local/bin:$PATH"
source ~/.bashrc  # 或 source ~/.zshrc

---

Q2: npm速度很慢

使用国内镜像源（淘宝镜像）：

# 临时使用
npm install --registry=https://registry.npmmirror.com

# 永久设置
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

---

Q3: npx权限错误

Windows:

# 以管理员身份运行PowerShell

macOS/Linux:

# 不要使用sudo运行npx
# 如果遇到权限问题，修复npm全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

---

Q4: 版本冲突

如果需要管理多个Node.js版本，推荐使用版本管理工具：

Windows: nvm-windows

# 安装nvm-windows后
nvm install 20.11.0
nvm use 20.11.0

macOS/Linux: nvm

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装Node.js
nvm install 20
nvm use 20

---

Q5: npx下载包很慢

# 方式1：使用国内镜像
npx --registry=https://registry.npmmirror.com @modelcontextprotocol/server-filesystem

# 方式2：先全局安装，再使用
npm install -g @modelcontextprotocol/server-filesystem
server-filesystem

---

下一步

安装完成后，你可以：

1. ✅ 运行 code/02_Connect2MCP.py 测试MCP客户端连接
2. ✅ 探索社区MCP服务器：https://github.com/modelcontextprotocol/servers
3. ✅ 继续学习第十章的其他内容

---

参考资源

• Node.js官网: https://nodejs.org/
• npm文档: https://docs.npmjs.com/
• npx文档: https://docs.npmjs.com/cli/v10/commands/npx
• MCP服务器列表: https://github.com/modelcontextprotocol/servers
• 淘宝npm镜像: https://npmmirror.com/

---

祝你学习愉快！ 🎉

如有问题，请参考常见问题部分或查阅官方文档。