English
中文 在 Joomla 中，当服务器返回 `500 - Whoops, looks like something went wrong` 错误时，这是 Joomla 的默认错误页面，通常由内部服务器错误（HTTP 500）触发，例如 PHP 致命错误、文件缺失或权限问题。要自定义这个页面，你需要覆盖 Joomla 的默认错误模板。以下是基于 Joomla 最新版本（截至 2025 年 2 月 22 日，例如 Joomla 5.x）的详细步骤，适用于 Windows 或其他环境。
---
### 错误页面的来源
- **位置**：默认错误页面来自 `layouts/joomla/system/error.php`（Joomla 核心布局文件）。
- **触发条件**：当 `error_reporting` 未开启调试模式（`development` 或 `maximum`）时，Joomla 显示简洁的“Whoops”消息，而不是详细的错误信息。
- **自定义方式**：通过模板覆盖或配置文件调整来替换此页面。
---
### 方法一：通过模板覆盖自定义错误页面
Joomla 允许通过当前活动模板覆盖系统布局文件。
#### 步骤
1. **找到当前模板**：
- 登录 Joomla 后台，前往 `System > Templates > Administrator Templates`（后台）或 `Site Templates`（前台），查看正在使用的模板（例如 `atum` 或自定义模板）。
- 假设后台模板为 `atum`，前台为 `cassiopeia`。
2. **创建覆盖目录**：
- 用 FTP 或文件管理器进入模板目录：
- 后台：`administrator/templates/atum/`
- 前台：`templates/cassiopeia/`
- 在模板根目录下创建 `html/layouts/joomla/system/` 文件夹结构。
3. **复制默认错误文件**：
- 从 Joomla 核心复制 `layouts/joomla/system/error.php`（位于 Joomla 安装根目录）到：
- 后台：`administrator/templates/atum/html/layouts/joomla/system/error.php`
- 前台：`templates/cassiopeia/html/layouts/joomla/system/error.php`
4. **自定义错误页面**：
- 编辑复制的 `error.php`，例如：
```php
<?php
defined('_JEXEC') or die;
use Joomla\CMS\Factory;
$app = Factory::getApplication();
$errorCode = $app->get('error_code', 500);
?>
<!DOCTYPE html>
<html lang="<?php echo $app->getLanguage()->getTag(); ?>">
<head>
<meta charset="utf-8">
<title>错误 <?php echo $errorCode; ?></title>
<style>
body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
h1 { color: #d9534f; }
p { font-size: 18px; }
</style>
</head>
<body>
<h1>哎呀，出错了！</h1>
<p>错误代码：<?php echo $errorCode; ?></p>
<p>很抱歉，我们遇到了问题。请联系管理员或稍后重试。</p>
<a href="/">返回首页</a>
</body>
</html>
```
- 你可以添加自定义 CSS、图片或逻辑（例如显示联系方式）。
5. **测试效果**：
- 触发一个 500 错误（例如临时删除关键文件或引入 PHP 错误）。
- 确保错误页面显示为自定义内容，而不是“Whoops”。
#### 注意事项
- **权限**：确保新文件可读（Windows 上检查安全设置，Linux 上用 `chmod 644`）。
- **缓存**：清除 Joomla 缓存（`System > Clear Cache`）以应用更改。
- **前后台分离**：根据错误发生位置（前端还是后台），选择覆盖对应模板。
---
### 方法二：修改全局错误处理（高级）
通过自定义 Joomla 的错误处理逻辑，完全接管 500 错误页面。
#### 步骤
1. **创建系统插件**：
- 在 `plugins/system/customerror/` 创建一个新插件（目录名随意，例如 `customerror`）。
- 文件结构：
- `customerror.php`（主插件文件）
- `customerror.xml`（清单文件）
2. **编写插件代码**：
- `customerror.php`：
```php
<?php
defined('_JEXEC') or die;
use Joomla\CMS\Plugin\CMSPlugin;
class PlgSystemCustomerror extends CMSPlugin
{
public function onError($error)
{
if ($error->getCode() == 500) {
http_response_code(500);
echo '<!DOCTYPE html>
<html>
<head><title>自定义 500 错误</title></head>
<body><h1>服务器错误</h1><p>抱歉，发生了意外错误。请稍后再试。</p></body>
</html>';
exit;
}
}
}
```
- `customerror.xml`：
```xml
<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade">
<name>System - Custom Error</name>
<version>1.0.0</version>
<creationDate>2025-02-22</creationDate>
<author>Your Name</author>
<description>Custom 500 error page</description>
<files>
<filename plugin="customerror">customerror.php</filename>
</files>
</extension>
```
3. **安装插件**：
- 将文件夹压缩为 `.zip`，在 `Extensions > Manage > Install` 上传安装。
- 启用插件：`Extensions > Plugins > System - Custom Error`。
4. **测试**：
- 触发 500 错误，确认显示自定义页面。
#### 注意事项
- **优先级**：确保插件加载顺序靠前（调整 `ordering` 字段）。
- **调试冲突**：若开启调试模式，Joomla 可能优先显示详细错误而非自定义页面。
---
### 方法三：调整服务器错误页面（备选）
如果 Joomla 未接管错误，可以在 Web 服务器级别自定义 500 页面。
- **Windows (IIS)**：
1. 编辑 `web.config`（Joomla 根目录）：
```xml
<system.webServer>
<httpErrors errorMode="Custom">
<remove statusCode="500" />
<error statusCode="500" path="/custom-500.html" responseMode="File" />
</httpErrors>
</system.webServer>
```
2. 创建 `custom-500.html` 文件。
- **Apache (XAMPP)**：
1. 编辑 `.htaccess`：
```
ErrorDocument 500 /custom-500.html
```
2. 创建静态 HTML 文件。
- **限制**：仅适用于服务器级错误（PHP 未处理的情况），不如 Joomla 内部自定义灵活。
---
### 注意事项
1. **调试模式影响**：
- 如果 `configuration.php` 中 `public $debug = 1` 或 `public $error_reporting = 'maximum'`，Joomla 会显示详细错误而非“Whoops”页面。自定义页面仅在非调试模式下生效。
2. **多语言支持**：
- 在 `error.php` 中使用 `JText::_('KEY')` 添加语言字符串，支持多语言。
3. **安全性**：
- 避免在自定义页面泄露敏感信息（如服务器路径、堆栈跟踪）。
4. **Windows 环境**：
- XAMPP 上修改文件后，重启 Apache。
- 确保模板文件夹可写（右键 > 属性 > 安全 > 授予权限）。
---
### 推荐方案
- **方法一（模板覆盖）**：最简单、无需编码，适合大多数用户。只需几分钟即可完成。
- **方法二（插件）**：适合需要动态内容或高级逻辑的技术用户。
- **方法三（服务器）**：仅作为 Joomla 未捕获错误的备用。
---
### 示例结果
假设你用方法一覆盖 `atum` 模板，触发 500 错误后，用户会看到：
```
错误 500
哎呀，出错了！
很抱歉，我们遇到了问题。请联系管理员或稍后重试。
[返回首页]
```
