配置设置

关于 XenForo 应如何连接至数据库所需的全部信息都位于src/config.php文件中。

实际上，config.php是一份src/config.php.default的副本文件。后者包含创建一个全新 XenForo 实例所需的全部必要信息。一般地，XenForo 安装程序会自动创建这个文件，但具体行为根据安装 XenForo 的方式决定。config.php中的字段控制着 XenForo 实例的基本功能，若错误配置则可能会导致网站无法正常运行。所以一旦遇到问题务必回滚修改。

此文档枚举所有config.php中的可用配置项。配置项的变量字面量名称务必与文档中的名称保持完全一致，其键值均区分大小写。无效的变量会被忽略。

数据库​

配置项默认值描述
$config['db']['host']'localhost'数据库主机地址。
$config['db']['port']3306数据库主机端口号。
$config['db']['socket']null数据库主机套接字。
$config['db']['username']''数据库用户名。
$config['db']['password']''数据库密码。
$config['db']['dbname']''数据库名。

表情符号​

配置项默认值描述
$config['fullUnicode']false此配置项负责通知 XenForo 是否已完全手动对网站中的所有内容执行 Unicode 转换。此操作用于支持文本内的表情符号。

由于 XenForo 2 自带 Unicode 格式支持，因此该配置项仅适用于那些从 XenForo 1 手动升级至版本 2 的情形。后者对应的情况下需要根据此文档手动执行一次 Unicode 转换。在该转换被执行且彻底完成之前，此配置项均应为false。

高级配置​

配置项默认值描述
$config['enableMail']true彻底禁用 XenForo 的所有电子邮件发送功能。网站永远不会再发送任何电子邮件。
$config['enableMailQueue']true禁用电子邮件队列。

队列中剩余的电子邮件将不会被发送，所有新电子邮件将在生成后立即发送，而不是排队等待批量发送。

$config['enableListeners']true禁用 XenForo 中的所有代码事件监听器。此操作会大幅关闭插件功能，因此如果某个插件出现故障，从而导致无法访问系统和控制面板，此功能可以帮助恢复访问。
$config['enableTemplateModificationCallbacks']true禁止所有已显式定义的模板修改使用 PHP 回调。

此配置项的作用与enableListeners类似，可用于重新访问因回调中断而无法正常运行的系统。

$config['enableGzip']true默认情况下，XenForo 会使用 gzip 来压缩系统所生成页面的最终 HTML 和 CSS 输出，然后在访客浏览器接收到数据时对其进行静默解压缩。此功能可以显著加快页面的加载时间，但如果你需要禁用此功能并将 HTML 和 CSS 以未压缩的纯文本形式发送，则可以将此配置项设置为false。
$config['enableContentLength']true通常情况下，XenForo 会发送Content-Length HTTP 标头。但在某些服务器配置中，内容可能会在 XenForo 发送和最终用户接收这两个节点之间被二次修改。

在这种情况下，Content-Length标头可能无法被正确地更新，因此应将其设置为false。

$config['enableTfa']true全站禁用两步验证。两步验证要求用户除使用用户名和密码之外，还需提供额外验证码信息方可登录。

若因两步验证出错而无法正常访问控制面板，或想要彻底禁止所有用户使用 2FA，则应将此配置项设置为false。

$config['enableLivePayments']true若此配置项设置为false，则网站完全不会处理任何支付行为。系统不会尝试与外部支付服务提供商连接，也不会尝试执行任何交易。此配置项一般用于站点测试。
$config['enableClickjackingProtection']true通常 XenForo 会发送值为SAMEORIGIN的X-Frame-Options HTTP 标头，作为防止恶意脚本点击劫持的一种手段。

启用此选项可以有效防止点击劫持攻击。此攻击会将网站置于iframe中并诱骗用户点击某些内容。但同时也可能禁用iframe嵌入的其它有效功能。应在了解其影响的情况下禁用此选项。

$config['enableReverseTabnabbingProtection']true启用此选项可以防止用户在点击外部网站链接时触发的基于反向标签抓取的网络钓鱼攻击。但同时此保护措施也可能会干扰依赖于修改链接点击处理方式的外部服务。应在了解其影响的情况下禁用此选项。
$config['enableApi']true若禁用此项，则关闭 XenForo 的 REST API 能力。向路径api/发起的请求将不再收到有效响应。
$config['enableAddOnArchiveInstaller']false此项控制对基于控制面板的 WEB 插件安装/升级系统的访问。启用后，具有必要权限的管理员可以上传包含 XenForo 插件的压缩包文件，并自动安装或升级它。

出于安全原因，此设置默认处于禁用状态。

$config['enableOneClickUpgrade']true若禁用此项，则关闭控制面板中的一键 XenForo 升级功能。

Cookie 设置​

下列配置允许自定义访客浏览器上的cookie行为。若出现无效或错误设置，则可能会导致您和您的访客无法登录到 XenForo 用户帐户，包括管理员控制面板。

修改这些值的主要理由应当是尝试在同一个域名部署多个 XenForo 实例。如果您的域名只对应了一个 XenForo 实例，那么就无需更改这些设置。

只有在确实需要且清楚自己在做什么的情况下才应更改这些值。如果遇到问题，请将这些值重置为默认值。

配置项默认值描述
$config['cookie']['prefix']'xf_'所有 Cookie 实际上都是通过其名称进行识别。每个功能对应独立 Cookie 的名称应当是唯一的。XenForo 设置的 Cookie 名称通常都带有前缀'xf_ '以便与其它系统设置的 Cookie 区分开来。更改此值的一个后果是：所有已登录用户的“记住登录状态”首选项将会被重置，以至于所有人下次访问此网站时都需要重新登录。

前缀的值只能使用字母、数字和下划线，且区分大小写。

$config['cookie']['path']'/'默认值'/'保证 XenForo Cookie 在网站的所有区域（路径下）可用。若想使这些 Cookie 仅在网站的特定路径下可用，则应修改此值，使其包含指向正确目标区域的相对目录路径，例如'/forums/MySpecialForum'。下面是一些示例值：

  • '/forum/'：Cookie 只能由位于http://example.com/forum下的页面读取，其中example.com是您的网站地址。

  • '/path/to/other/folder/'：Cookie 只能由位于path/to/other/folder目录中的页面读取。位于此位置上方文件夹中的页面无法读取Cookie ，如http://example.com/path、http://example.com/path/to和http://example.com/path/to/other。

$config['cookie']['domain']''与上面的['cookie']['path']似，此设置允许指定可以读取 Cookie 的域名。通常情况下无需设置此值，且若想更改此值，务必格外小心，因为一旦 XenForo 无法再读取自身所设置的 Cookie，网站的核心功能就会无法使用，如保持登录态。

设置此值的目的是允许在多个子域名之间共享 Cookie，例如当此项设为'.example.com'，则 example.com 的所有子域名都将开始共享实例 Cookie。但在绝大多数情况下根本无需设置此参数。

数据和 JavaScript 位置​

若想更改 XenForo 存储数据（如头像、附件和 JavaScript 文件）的位置，则可以通过修改这些设置来实现。

配置项默认值描述
$config['externalDataPath']'data'XenForo 将头像和附件缩略图等文件保存在该目录中，这些文件会通过 Web 服务器直接提供给浏览器。
$config['externalDataUrl']'data'XenForo 将此路径告知浏览器，然后浏览器尝试在 URL 下的该路径中获取头像和附件缩略图等文件。
$config['internalDataPath']'internal_data'该目录包含不会直接提供给 Web 浏览器客户端的文件，如附件。
$config['codeCachePath']'%s/code_cache'该目录负责存储用于加速 XenForo 运行速度的 PHP 可执行缓存文件。
$config['tempDataPath']'%s/temp'定义用于存储临时文件的目录路径，如刚刚上传的附件，这些附件在保存到最终存储位置之前需要经过处理。
$config['javaScriptUrl']'js'定义js文件夹的实际位置，XenForo 会在该文件夹中找到核心前端功能文件。

路径变量​

以Path结尾的变量名指的是服务器上相对于 XenForo 根目录的内部文件系统路径。例如假设 XenForo 安装于/users/yourname/htdocs/xenforo，那么：

值实际指向
data/users/yourname/htdocs/xenforo/data
/users/yourname/htdocs/xenforo/data/users/yourname/htdocs/xenforo/data
../another-folder/users/yourname/htdocs/another-folder

URL 变量​

以Url结尾的变量名指的是从 XenForo 根目录开始的相对 URL 路径。例如假设 XenForo 的实际访问 URL 为http://example.com/xenforo，那么：

值实际指向
datahttp://example.com/xenforo/data
../another-folderhttp://example.com/another-folder
/a-root-folderhttp://example.com/a-root-folder
/xenforo/my-folderhttp://example.com/xenforo/my-folder

注意：① 所有路径变量对应的目录必须具有 Web 服务器的写入权限 (chmod 777)，否则 XenForo 将无法在这些位置存储数据。② 如果这些路径和 URL 变量设置错误，则XenForo 核心将会无法正常工作。请仅在您完全清楚自己在做什么的情况下再进行更改。

数据库 Adapter​

配置项默认值描述
$config['db']['adapterClass']'XF\Db\Mysqli\Adapter'用于驱动 XenForo 与数据库之间连接的中间件。若使用的数据库是 MySQL 及其衍生类型，则无需修改此项。

HTTP 客户端​

这些配置项控制内部 XenForo HTTP 客户端的行为，该客户端用于在使用图像和链接代理时联网获取资源，例如图像和网页。

配置项默认值描述
$config['http']['sslVerify']null强制 XenForo 在请求资源时验证其访问的使用 SSL/HTTPS 的网站的 SSL 证书。
$config['http']['proxy']null所有内部网络请求所经由的代理服务器的地址。

缓存​

所有大型 XenForo 网站均应使用缓存机制来加快页面的生成速度。

此页面包含所有关于缓存及其配置项的详细文档。

配置项默认值描述
$config['cache']['enabled']false如果配置了缓存，则可以随时通过将此选项的值设置为false来禁用它。

页面级缓存​

配置项默认值描述
$config['pageCache']['enabled']false配置缓存机制后，可以使用pageCache为访客用户缓存整个页面。此功能虽然效果显著，但会消耗大量内存资源，因此默认处于禁用状态，直到确认能够为其分配充足的资源为止。所有关于页面缓存的详细信息和选项均在此部分中进行了说明。

面向开发与设计人员​

调试模式​

调试模式是 XenForo 用于调试或开发目的的一种特殊状态。

配置项默认值描述
$config['debug']false将此项设置为true是某些功能正常运行的必要条件，包括设计器模式和开发模式。

绝对、绝对不要在现网生产环境中启用调试模式。

启用调试模式后，执行和页面生成速度不仅会比禁用调试模式时慢得多，且内部 SQL 查询状态等重要信息还会泄露给访问用户。仅当处于受保护的私有 XenForo 实例环境中，且该环境免受任何潜在恶意访问者的影响时，才应启用调试模式。

设计模式​

设计模式是用于设计 XenForo 主题的一项高级功能，该模式允许直接在文件系统中编辑模板，而非使用管理员控制面板中的模板编辑器。

配置项默认值描述
$config['designer']['enabled']false打开/关闭设计模式。
$config['designer']['basePath']'src' . \DIRECTORY_SEPARATOR . 'styles'控制 XenForo 期望找到设计模式当前正在使用的模板等文件的位置。

开发模式​

开发者模式是为 XenForo 插件开发者准备的一项高级功能。

配置项默认值描述
$config['development']['enabled']false开启/关闭开发模式。
$config['development']['defaultAddOn']''系统会自动将管理员控制面板中新建内容所属的插件设置更改为此配置项所指定的插件 ID 对应的插件。
$config['development']['skipAddOns]null应为插件 ID 数组。在执行开发工具（如导入和导出核心数据）时，数组['addOn1', 'addOn2']中的插件都将被跳过。
$config['development']['throwJobErrors']null启用此选项，则执行开发工具（如执行插件构建脚本）时通常会被静默忽略的错误都将被抛出并显示，从而中断作业进程。常用于调试开发作业输出问题。
$config['development']['fullJs']false控制系统是应该使用标准的、经过精简和打包的 JavaScript 文件，还是应该使用完整、分离、未经压缩的文件。这些文件的最终功能与压缩后的文件相同，但具备代码可读性，因而可以更好地进行调试。

使用完整的 JavaScript 文件会导致网站生成更多 HTTP 请求并消耗更多带宽，从而导致访问用户的体验变慢，因此不建在实际生产环境中启用。

杂项​

配置项默认值描述
$config['globalSalt']'<unique value>'此变量定义了一个密钥值，用于对各种缓存、Cookie 和其它数据的值进行加盐处理，以防止数据被恶意攻击者窃取或伪造。切勿向任何人透露全局加盐值，否则会危及您的网站安全。通常情况下 XenForo 会生成自己的安全全局盐值，因此只有您想要定义自己的盐值时才需要更改此项。
$config['checkVersion']true启用此项，则系统将检查存储在 XenForo PHP 源代码中的版本号是否与存储在 XenForo 数据库中的版本号匹配，如果版本号不匹配（例如刚刚上传了准备执行升级的文件，但尚未实际运行升级程序），则会阻止普通访客访问网站。
$config['passwordIterations']10配置基于 bcrypt 的密码存储系统的强度。数值越高安全性越高，但此设置值每增加一倍，生成或验证密码所需的时间大致会翻倍，从而导致服务器使用率升高。
$config['maxImageResizePixelCount']20000000XenForo 尝试调整图片大小的最大尺寸（以像素总数计）。大于此尺寸的图像将不会被调整大小，因此可能会被打回。此尺寸的计算方法为宽度乘以高度。
$config['adminLogLength']60管理员控制面板中所有管理员活动日志的保留天数。超过此天数后，这些日志将从数据库中删除。
$config['chmodWritableValue']0如果此值非零，则 XenForo 创建的所有文件都会自动更改其权限（chmod）为该值。目录也会被更改权限，但它们始终对用户、组和所有用户都可执行。

在大多数情况下，XenForo 会自动确定正确的权限值。

$config['proxyUrlFormat']'proxy.php?{type}={url}&hash={hash}'定义使用图片和链接代理功能的内容的最终链接格式。格式必须包含{type}、{url}和{hash}，且必须指向proxy.php，除非有其它程序或系统来处理代理请求。
$config['jobMaxRunTime']8配置处理作业在暂停以进行后续处理之前允许运行的秒数（如果可能）。
$config['fsAdapters'][]定义系统可用的文件系统适配器列表。
上一页：欢迎使用 XenForo 2 下一页：REST API