---
title: "1.8 Localhost 与端口"
description: "理解本地开发环境，掌握端口管理"
chapter: "第一章"
---

# 1.8 Localhost 与端口

> **阅读完本节后，你将会收获：**
>
> - 理解 localhost 的作用和 IP 地址的基础概念
> - 掌握端口的含义和常见端口
> - 学会启动/停止开发服务器，处理端口占用问题

创建好项目后，下一步就是启动开发服务器，在浏览器中查看你的应用。

## 基本概念

### Localhost 本地主机

**localhost** 是你电脑的"内部地址"，用于本地开发测试。

| 地址 | 作用 |
|------|------|
| `localhost` | 本地主机名，自动解析为 127.0.0.1 |
| `127.0.0.1` | 本地回环 IP 地址 |
| `http://localhost:3000` | 本地运行的第 3000 端口服务 |

两者是等价的：

```bash
ping localhost      # 和下面效果相同
ping 127.0.0.1
```

::: tip localhost vs 公网地址

| 开发环境 | 生产环境 |
|----------|----------|
| `localhost:3000` | `https://example.com` |
| 只有你能访问 | 所有人都能访问 |
| 用于开发调试 | 用于正式运营 |

:::

### 端口 Port

**端口**就像房子的门，一个 IP 地址可以有 65535 个端口，每个端口可以运行不同的服务。

如果把 IP 地址比作**大楼地址**，端口就是**房间号**：

| 端口 | 服务 | 应用 |
|------|------|------|
| 3000 | Next.js 开发服务器 | `http://localhost:3000` |
| 5173 | Vite 开发服务器 | `http://localhost:5173` |
| 8000 | Python HTTP 服务器 | `http://localhost:8000` |

**常见开发端口**：

| 端口 | 用途 |
|------|------|
| 3000 | Next.js、Express |
| 5173 | Vite |
| 8000/8080 | 通用备用端口 |
| 80 | HTTP（生产环境，可省略） |
| 443 | HTTPS（生产环境，可省略） |

**端口号规则**：

- **0-1023**：系统端口，需要管理员权限
- **1024-49151**：注册端口，常见服务使用
- **49152-65535**：动态端口，临时使用

::: details 🎮 点击体验：Localhost 端口可视化
<LocalhostVisualizer />

> 💡 **练习**：点击空闲房间启动服务，点击已占用房间触发 EADDRINUSE 错误，切换开发/生产模式查看架构差异
>
> 🎯 **核心概念**：端口就是"房间号"，一个端口同时只能运行一个服务
:::

## 启动开发服务器

```bash
# 进入项目目录（my-app 改为你创建的项目名）
cd my-app

# 安装依赖（首次运行）
pnpm install

# 启动开发服务器
pnpm dev
```

::: tip 为什么先安装依赖？

`pnpm install` 会下载项目所需的所有代码包（依赖），没有这一步，项目无法运行。这就像拼装家具前，需要先确认所有零件都齐全了。

:::

启动后会显示类似信息：

```
▲ Next.js 16.1.4
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 1.2s
```

打开浏览器访问 `http://localhost:3000`。

::: tip 什么时候需要运行 pnpm dev？

**每次开始工作**时都需要运行：

- 第一次打开项目
- 修改代码后想看效果（服务器会自动刷新，不需要重启）
- 关闭服务器后想继续工作

服务器启动后可以一直开着，直到你完成工作。

:::

::: tip Network 地址有什么用？

Local 地址只有你能访问。Network 地址可以让局域网内其他设备（如手机）访问，用于测试移动端效果。

:::

## 停止开发服务器

在终端中按 `Ctrl + C` 即可停止。

| 系统 | 操作 |
|------|------|
| Windows / Mac / Linux | 按 `Ctrl + C` |

::: warning 服务器关闭后页面会失效

当你关闭终端或按 `Ctrl+C` 停止服务器后，`localhost:3000` 的页面会无法访问。

**这是正常的**：开发服务器只在运行时提供服务。下次工作只需重新运行 `pnpm dev`。

:::

## 端口占用处理

启动时如果提示端口被占用：

```
Error: listen EADDRINUSE: address already in use :::3000
```

**直接让 AI 帮你解决**：把报错信息发给 AI，它会帮你处理。

你也可以手动更换端口：

```bash
# Next.js：指定端口启动
pnpm dev -- -p 3001
```

::: tip 端口冲突的自动处理

现代开发工具（如 Next.js 14+）会自动检测端口占用，如果 3000 被占用，会自动尝试 3001、3002...

**但如果看到 EADDRINUSE 报错**，说明自动检测失败，让 AI 帮你处理即可。

:::

::: tip AI 可用的命令

如果你想知道 AI 会用什么命令解决，参考如下：

**Mac / Linux**：

```bash
lsof -ti:3000 | xargs kill -9
```

一条命令搞定：查找占用 3000 端口的进程并直接终止。

**Windows**：

```powershell
netstat -ano | findstr :3000
```

先查看占用端口的进程 PID，然后：

```powershell
taskkill /PID 12345 /F
```

把 `12345` 替换为实际的 PID。

:::

## 常见问题

### Q: 为什么启动服务器后浏览器自动打开 localhost？

开发工具的便利功能。Vercel、Vite 等工具会自动检测到服务器启动并打开浏览器。

### Q: 修改代码后页面没变化？

开发服务器支持**热重载**，保存文件后自动刷新。如果没有：

- 检查服务器是否正常运行
- 尝试手动刷新浏览器（F5）

### Q: 可以在局域网访问 localhost 吗？

不可以。`localhost` 只能在本机访问。局域网访问需要使用本机的局域网 IP：

```bash
# 查看本机 IP
ipconfig        # Windows
ifconfig        # Mac/Linux

# 局域网访问
http://192.168.1.100:3000
```

### Q: 生产环境也用 3000 端口吗？

可以，但通常不直接让用户访问 3000 端口。

**生产环境的典型架构**：

```mermaid
graph LR
    A[用户浏览器] --> B[https://example.com<br/>80/443 端口]
    B --> C[Nginx / OpenResty<br/>反向代理]
    C --> D[你的应用<br/>3000 端口]

    style A fill:#e3f2fd
    style C fill:#fff3e0
    style D fill:#f3e5f5
```

用户访问 `https://example.com` 时，请求先到 Nginx（监听 80/443 端口），然后 Nginx 转发给你的应用（3000 端口）。

**当然，也可以直接让用户访问 IP + 端口**：

```
http://你的服务器IP:3000
```

但这样不太美观，而且暴露了端口号。推荐使用 Nginx 做反向代理，用户只需要记住域名。

## 核心理念

**Localhost 是本地开发的基础**。

- ✅ localhost = 127.0.0.1，都指向本地计算机
- ✅ 端口区分服务，同一台电脑可运行多个服务
- ✅ 开发用 localhost，生产用域名
- ✅ 一个端口同时只能有一个进程
- ✅ `Ctrl + C` 停止服务器

## 相关内容

- 详见：[1.4 Terminal 终端入门](./04-terminal-basics.md)
- 详见：[1.7 创建项目](./07-creating-project.md)
- 前置：[1.3 浏览器与服务器基础](./03-browser-server.md)