> 来源：https://mac-cms.com/cms/cms-troubleshooting
> 简介：MacCMS（苹果CMS）V10 部署常见故障排查，每条按症状、原因、解决整理：除首页外全404的 Nginx/Apache 伪静态、PHP8 类型报错换 PHP7、数据库连接失败、后台打不开、采集无数据、接口返回空、CORS 跨域、重装删 install.lock。
> 更新：2026-11-02

# MacCMS 部署排障大全

自建 MacCMS 最容易卡住的就是环境和配置。下面把常见故障按"**症状 → 原因 → 解决**"列清楚，照着排基本都能解决。MacCMS V10 基于 ThinkPHP5，很多问题其实是框架和环境的通病。

## 除首页外全部 404

**症状**：首页能打开，点进任何栏目、详情、后台都报 404。

**原因**：伪静态没配。ThinkPHP5 的路由要靠 Web 服务器把请求转发给入口文件，没配规则时只有首页能命中。

**解决**：按你的服务器加伪静态规则。

Nginx：

```nginx
if (!-e $request_filename) {
    rewrite ^/index.php(.*)$ /index.php?s=$1 last;
    rewrite ^/admin.php(.*)$ /admin.php?s=$1 last;
    rewrite ^/api.php(.*)$ /api.php?s=$1 last;
    rewrite ^(.*)$ /index.php?s=$1 last;
    break;
}
```

Apache（网站根目录放 `.htaccess`，并确认开了 `mod_rewrite`）：

```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ index.php?s=$1 [QSA,PT,L]
</IfModule>
```

::: warning 改过入口名的注意
如果你把 `admin.php`、`api.php` 改成了别的名字，上面规则里对应的那行也要一起改。
:::

## PHP 8.x 各种类型报错

**症状**：装好或升级 PHP 后，前台 / 后台白屏或报错，常见一条是：

```
Argument #2 ($array) must be of type ?array, string given
```

**原因**：MacCMS V10 用的 ThinkPHP5 比较老，和 PHP 8.x 的严格类型声明冲突。能勉强跑，但各种边角会出错。

**解决**：把 PHP 版本切回 **7.x**（宝塔面板里网站设置能直接切）。PHP 7.x 是跑 MacCMS V10 最稳的选择，装站时就建议直接选它，少踩这类坑。

## 数据库连接失败

**症状**：访问报数据库连接错误，或安装时填完库信息过不去。

**原因**：数据库配置填错，或库 / 账号还没建。

**解决**：检查 `/application/database.php`：

```php
return [
    'hostname' => '127.0.0.1',
    'database' => '数据库名',
    'username' => '用户名',
    'password' => '密码',
    'hostport' => '3306',
];
```

逐项核对：`hostname` 一般是 `127.0.0.1`、`hostport` 默认 `3306`；确认数据库已创建、账号密码正确、账号对这个库有权限。

## 后台打不开 / 后台 404 / 提示"请将 admin.php 改名"

**症状**：前台正常，但进后台打不开，看到一句"请将后台入口文件 admin.php 改名"，或报 404，或忘了后台在哪。

**原因**：有两种，先分清：

1. **没改名**：MacCMS 的 `admin.php` 源码里写死了强制改名检查（第 36–39 行）——只要访问路径里还带着 `/admin.php`，程序直接 `echo` 一句"请将后台入口文件 admin.php 改名…"然后 `exit`，**根本不会加载后台**。这不是报错，是源码强制要求你改名。`index.php` / `api.php` 没有这个检查。
2. **改过名但地址/伪静态不对**：装完改过文件名后用老地址访问，或伪静态没配到后台入口那一行。

**解决**：

- 装完**必须**把 `admin.php` 改名（见[安装教程](/cms/index#安装完成)），改成别人猜不到的名字如 `admin7854.php`，用"域名 + 新文件名"访问，例如 `https://域名/admin7854.php`。
- 还在用 `admin.php` 访问、看到改名提示：这是正常拦截，照上一步改名即可。
- 改过名仍 404：回头检查伪静态规则里有没有对应入口文件那条（见上面"除首页外全部 404"），改过名的话规则里的 `admin.php` 也要同步改成新文件名。

## 采集之后没有数据

**症状**：采集任务跑了，前台却没影视数据。

**原因**：常见三种——分类没绑定、资源站本身没这个分类的数据、采集任务参数不对。

**解决**：

1. 进后台确认采集时**分类绑定**做了：把资源站的分类映射到你自己的分类上，没绑的分类不会采。
2. 换个有数据的分类试，确认资源站该分类确实有内容。
3. 看采集日志有没有报错。
4. 采集流程完整步骤见[采集教程](/cms/cms-collect)。

## 接口返回空数据

**症状**：对接空壳影视或别的 App 时，接口能打开但 `list` 是空的。

**原因**：库里本来就没数据，或请求的分类 ID 不对。

**解决**：先确认库里有影视数据，再直接测接口：

```
/api.php/provide/vod/?ac=videolist
```

能返回带 `list` 的 JSON 就说明接口本身没问题，再逐步加 `t=分类ID`、`wd=关键词` 等参数定位。

## CORS 跨域取不到数据

**症状**：接口在浏览器里能打开，App 或网页端却取不到数据，控制台报跨域。

**原因**：服务器没放开跨域访问。

**解决**：在 Web 服务器给接口加跨域响应头。Nginx 示例：

```nginx
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Allow-Headers "Content-Type";
```

生产环境建议把 `*` 换成具体允许的来源域名，别一直全开。

## 想重装 / 清掉安装状态

**症状**：想重新走一遍安装，但访问域名直接进了前台，不弹安装界面。

**原因**：装过一次后会生成安装锁文件，挡住重复安装。

**解决**：删掉锁文件，再访问域名就会重新进安装界面：

```
/application/data/install/install.lock
```

::: warning 重装会动数据
重装可能覆盖现有数据，操作前先备份数据库。
:::

---

装完别忘了做[安全加固](/cms/cms-security)，自建站暴露在公网上，不加固风险不小。