---
title: "5.2.8 部署常见问题"
order: 9
---


![05-advanced_5.2-deployment_5.2.8-faq.png](/images/Basic/05-advanced_5.2-deployment_5.2.8-faq.png)
# 5.2.8 部署常见问题

部署过程中遇到问题是正常的。这里整理了最常见的问题和解决方案。

## 问题速查表

| 问题 | 可能原因 | 解决方法 |
|------|---------|---------|
| 部署失败 | 代码有语法错误 | 先在本地确认能正常运行 |
| 页面空白 | 入口文件路径不对 | 确保 `index.html` 在项目根目录 |
| 样式丢失 | CSS 路径使用了绝对路径 | 改用相对路径（如 `./style.css`） |
| 图片不显示 | 图片路径错误或文件名大小写 | 检查路径和文件名大小写 |
| 功能不工作 | JavaScript 报错 | 打开浏览器控制台（F12）查看错误 |
| 大陆无法访问 | DNS 污染 | 换用 Zeabur 或帽子云 |
| 加载很慢 | 资源文件太大 | 压缩图片，检查是否有不必要的大文件 |
| 更新后没变化 | 浏览器缓存 | 强制刷新（Ctrl+F5）或清除缓存 |

## 问题详解

### 问题 1：部署失败，构建报错

**现象**：点击部署后，状态一直显示"Building"然后变成"Failed"。

**排查步骤**：

1. 查看构建日志，找到红色的错误信息
2. 检查本地项目是否能正常运行
3. 确认所有必要的文件都已提交到 GitHub

**常见原因**：
- 代码有语法错误
- 缺少必要的配置文件
- 依赖没有正确安装

**AI 求助模板**：

```
我在 [Zeabur/Vercel] 上部署项目时，构建失败了。

构建日志显示这个错误：
[粘贴红色的错误信息]

我的项目是一个 [纯 HTML/CSS/JS 静态网站 / React 项目 / ...]。
本地运行是 [正常的 / 也有问题]。

请帮我分析原因并给出解决方案。
```

### 问题 2：页面空白

**现象**：部署成功了，但打开网址是空白页面。

**排查步骤**：

1. 打开浏览器开发者工具（F12）
2. 查看 Console（控制台）是否有红色错误
3. 查看 Network（网络）是否有 404 错误

**常见原因**：
- `index.html` 不在根目录
- JavaScript 文件路径错误导致脚本加载失败
- 使用了绝对路径，线上环境找不到文件

**解决方法**：

```html
<!-- 错误：绝对路径 -->
<script src="/js/app.js"></script>

<!-- 正确：相对路径 -->
<script src="./js/app.js"></script>
```

### 问题 3：样式丢失

**现象**：页面能显示，但样式完全乱了，或者没有样式。

**常见原因**：
- CSS 文件路径错误
- CSS 文件没有被提交到 GitHub
- 使用了绝对路径

**解决方法**：

```html
<!-- 错误 -->
<link rel="stylesheet" href="/style.css">

<!-- 正确 -->
<link rel="stylesheet" href="./style.css">
```

### 问题 4：功能不工作

**现象**：页面显示正常，但按钮点击没反应，功能不工作。

**排查步骤**：

1. 打开浏览器控制台（F12 → Console）
2. 查看是否有红色错误信息
3. 尝试触发功能，看是否有新的错误出现

**AI 求助模板**：

```
我的待办清单部署后，[添加任务 / 删除任务 / ...] 功能不工作了。

浏览器控制台显示这个错误：
[粘贴错误信息]

本地运行时功能是正常的。
请帮我分析原因。
```

### 问题 5：更新后网站没变化

**现象**：代码已经推送到 GitHub，但网站还是旧版本。

**可能原因**：
1. 部署还没完成（去控制台查看状态）
2. 浏览器缓存

**解决方法**：
- 等待部署完成（通常 1-2 分钟）
- 强制刷新页面：Windows 按 `Ctrl+F5`，Mac 按 `Cmd+Shift+R`
- 打开隐私模式/无痕模式访问

## 万能解决方案

当你遇到任何部署问题时，都可以用这个模板向 AI 求助：

```
我在部署网站时遇到了问题。

【环境信息】
- 部署平台：[Zeabur / Vercel / Netlify / ...]
- 项目类型：[纯 HTML/CSS/JS / React / Vue / ...]
- 本地运行：[正常 / 有问题]

【问题描述】
[描述你遇到的具体问题]

【错误信息】
[粘贴完整的错误信息，包括构建日志或浏览器控制台的错误]

【已尝试的方法】
[列出你已经尝试过的解决方法]

请帮我分析原因并给出解决方案。
```

::: tip 记住
遇到问题不要慌。部署问题通常都有明确的错误信息，把错误信息发给 AI，大多数问题都能快速解决。
:::

→ [5.2.9 本节检查清单](./5.2.9-checklist.md)