Extension:Scribunto

This page is a translated version of the page Extension:Scribunto and the translation is 76% complete.
此扩展已绑定在MediaWiki 1.34及以上版本。 因此您不需要再次下载。 然而,您仍需要跟随提供的其他指示。
本扩展在可执行程序上运行。 为了让该扩展工作,你必须在你的主机上有运行可执行文件的权限。
MediaWiki扩展手冊
OOjs UI icon advanced-invert.svg
Scribunto
發布狀態: 穩定版本
实现 解析器扩展
描述 提供在 MediaWiki 页面里嵌入脚本语言的框架
作者
  • Victor Vasiliev
  • Tim Starling
和其他人
最新版本 持续更新
兼容性政策 快照跟随MediaWiki发布。 master分支不向後兼容。
MediaWiki >= 1.38.0
PHP 5.5+
许可协议 GPL-2.0-or-later AND MIT
下載
Module (ns:828), Talk_Module (ns:829)
  • $wgScribuntoDefaultEngine
  • $wgScribuntoSlowFunctionThreshold
  • $wgScribuntoGatherFunctionStats
  • $wgScribuntoUseGeSHi
  • $wgScribuntoUseCodeEditor
  • $wgScribuntoEngineConf
翻譯Scribunto扩展,若在translatewiki.net可用

检查使用和版本矩阵。

問題 尚未完成的工作 · 报告錯誤

Scribunto (Latin: "they shall write/let them write (in the future)") 扩展可以在MediaWiki软件中嵌入脚本。

目前唯一被支持的脚本语言是Lua。 Scribunto Lua脚本在一个名为Module的命名空间里。

许可协议

该扩展包含使用GNU通用公共许可证v2.0或更高版本(GPL-2.0+)的代码以及使用MIT许可证(MIT)的代码。

需求

PCRE版本兼容性

推荐使用PCRE 8.33+。 你可以通过以下方法看到PHP所使用的PCRE的版本:查看phpinfo()页面,或在命令行使用以下命令。

php -r 'echo "pcre: " . ( extension_loaded( "pcre" ) ? PCRE_VERSION : "no" ) . "\n";'

CentOS 6 和 RHEL 6 卡在 PCRE 7 上,需要升级。

在使用旧版本的服务器上更新到 8.33 可能比较复杂。 更多细节在Updating to PCRE 8.33 or Higher

PHP pcntl (LTS)

MediaWiki版本:
1.25 – 1.28

MediaWiki 1.25 至 1.28 的 Scribunto 版本需要 PHP 的 pcntl扩展,如果您想使用“LuaStandalone”(即在单独的子进程中运行),该扩展名仅在 Unix/Linux 平台上可用。 在针对MediaWiki 1.29发布的Scribunto中这个依赖被移除。

你可以访问phpinfo()网页以检查pcntl的支持是否已经启用,或者在命令行输入以下命令:

php -r 'echo "pcntl: " . ( extension_loaded( "pcntl" ) ? "yes" : "no" ) . "\n";'

PHP mbsting 扩展

PHP需要启用 mbstring 扩展。

您可以通过查看phpinfo()网页或使用以下命令从命令行检查是否启用了mbstring支持:

php -r 'echo "mbstring: " . ( extension_loaded( "mbstring" ) ? "yes" : "no" ) . "\n";'

Lua 二进制

捆绑的二进制文件

Scribunto与Linux(x86和x86-64)、Mac OS X Lion和Windows(32位和64位)的Lua二进制发行版捆绑在一起。

Scribunto应该在以下情况下为您提供开箱即用的服务:

  1. 您的web服务器在上述平台之一上运行。
  2. PHP的proc_open函数不受限制。[1]
  3. 你的网络浏览器已被配置为允许MediaWiki树中的二进制文件的执行。
  注意: 可能需要设置执行权限,例如,在Linux使用:
chmod 755 /path/to/extensions/Scribunto/includes/engines/LuaStandalone/binaries/lua5_1_5_linux_64_generic/lua
If you are using SELinux in "Enforcing" mode on your server, you might need to set a proper context for the binaries. Example for RHEL/CentOS 7:
chcon -t httpd_sys_script_exec_t /path/to/extensions/Scribunto/includes/engines/LuaStandalone/binaries/lua5_1_5_linux_64_generic/lua

额外的二进制

如果您的Web服务器的操作系统不在上面的列表中,则可能需要额外的Lua二进制发行版,可以从http://luabinaries.sourceforge.net/或从你的Linux发行中获得。

只支持Lua 5.1.x的二进制文件。

在你的web浏览器中安装了适当的二进制文件后,使用如下代码配置文件的地址:

# 其中,Lua是二进制文件的名称。
# 例如,SourceForge LuaBinaries 5.1.5 - Release 2 name the binary file lua5.1
$wgScribuntoEngineConf['luastandalone']['luaPath'] = '/path/to/binaries/lua5.1';

注意你不应该添加上面的行,除非你确认Scribunto的内置二进制对你来说不起作用。

LuaJIT,尽管理论上兼容,但并不受支持。

不再支持是因为幽灵漏洞和比特腐烂的问题(phab:T184156)。

安裝

  • 下载文件,并将其放置在您extensions/文件夹中的Scribunto目录内。
  • 将下列代码放置在您的LocalSettings.php 的底部:
    wfLoadExtension( 'Scribunto' );
    $wgScribuntoDefaultEngine = 'luastandalone';
    
  • 设置与此扩展捆绑的Lua二进制文件的执行权限:
chmod a+x /path/to/extensions/Scribunto/includes/engines/LuaStandalone/binaries/yourOS/lua
  • 如果强制执行SELinux,请将type设置为httpd_sys_script_exec_t
chcon -t httpd_sys_script_exec_t /path/to/extensions/Scribunto/includes/engines/LuaStandalone/binaries/yourOS/lua
  •   完成 – 在您的wiki上导航至Special:Version,以验证已成功安装扩展。

致使用MediaWiki 1.29或更早版本的用户:

上面的说明介绍的是安装此扩展的新方法,它使用wfLoadExtension()。 如果您需要在早期版本(MediaWiki 1.29和更早版本)中安装此扩展,而不是wfLoadExtension( 'Scribunto' );,您需要使用:

require_once "$IP/extensions/Scribunto/Scribunto.php";


Vagrant installation:

  • 如果使用Vagrant ,请通过vagrant roles enable scribunto --provision安装

可选安装

集成扩展

为能使用有语法高亮和自动缩进的代码编辑器,提供更舒适的用户界面,请安装下列扩展:

MediaWiki版本:
1.30

然后在所有插件注册后,在你的LocalSettings.php中,添加:

$wgScribuntoUseGeSHi = true;
$wgScribuntoUseCodeEditor = true;

Lua 沙盒

我们开发了一个用C语言编写的PHP扩展,称为LuaSandbox。 可以用作独立二进制文件的替代,并且性能更佳。 详细信息和安装指引,参见LuaSandbox

如果你最初安装扩展以使用Lua独立二进制文件,请务必使用以下配置设置更新LocalSettings.php

$wgScribuntoDefaultEngine = 'luasandbox';

配置

有以下几个用于配置的变量:

$wgScribuntoDefaultEngine
选择默认引擎。 有效值为$wgScribuntoEngineConf中的键,默认为'luasandbox''luastandalone'
$wgScribuntoUseGeSHi
安装了扩展:语法高亮 后,将此设为true以在显示模块页面时使用它。(MediaWiki 1.30或更早。)
$wgScribuntoUseCodeEditor
安装了扩展:代码编辑器 后,将此设为true以在编辑模块页面时使用它。(MediaWiki 1.30或更早。)
$wgScribuntoEngineConf
引擎配置的关联数组。 键时$wgScribuntoDefaultEngine的有效值,值是配置数据的关联数组。 每个配置数组都必须包含一个'class'键,命名要使用的ScribuntoEngineBase子类。

LuaStandalone

$wgScribuntoEngineConf中使用以下键用于Scribunto_LuaStandaloneEngine。 通常你会将其设为类似于以下内容

$wgScribuntoEngineConf['luastandalone']['key'] = 'value';
luaPath
指定到Lua解释器的路径。
errorFile
指定文件的路径,可由Web服务器用户写入,其中将记录来自独立解释器的错误和调试输出。
默认情况下不记录独立解释器产生的错误输出。 配置输出:
$wgScribuntoEngineConf['luastandalone']['errorFile'] = '/path/to/file.log';
memoryLimit
为Linux上的独立解释器指定内存限制,以字节为单位(使用ulimit强制执行)。
cpuLimit
为Linux上的独立解释器指定CPU时间限制,以秒为单位(使用ulimit强制执行)。
allowEnvFuncs
设为true以允许在模块内使用setfenv和getfenv。

LuaSandbox

$wgScribuntoEngineConf中使用以下键用于Scribunto_LuaSandboxEngine。 通常你会将其设为类似于以下内容

$wgScribuntoEngineConf['luasandbox']['键'] = '值';
memoryLimit
指定内存限制,以字节为单位。
cpuLimit
指定CPU时间限制,以秒为单位。
profilerPeriod
在Lua分析器的部分中指定轮询之间的时间。
allowEnvFuncs
设为true以允许在模块内使用setfenv和getfenv。

用法

脚本在称为模块的命名空间中。 每个模块都有一系列函数,可以在像这样的维基文本语法中调用:

{{#invoke: Module_name | function_name | arg1 | arg2 | arg3 ... }}

Lua

学习Lua

Lua是一种简单的编程语言,用于让初学者可以使用。 Lua的快速速成课程,可以尝试Learn Lua in 15 Minutes

Lua语言的最全面的介绍是书籍《Programming in Lua》。 第一版(适用于Lua 5.0)可在线获得,主要与Scribunto使用的Lua 5.1版本相关:

参考手册也比较有用:

Lua环境

在Lua中,所有全局变量和函数的集合称为环境(environment)。

每个{{#invoke:}}调用会在一个单独的环境中运行。 一个{{#invoke:}}中定义的变量不会在另一个中有效。 这种限制是必要的,以维持维基文本解析器实现的灵活性。

脚本运行的环境与标准Lua中的环境不太一样。 这种差别会在扩展:Scribunto/Lua参考手册中指出。

调试控制台

 
调试控制台的使用例子
参见: Extension:Scribunto/Debug console

编辑Lua模块时,编辑框底部会有一个“调试控制台”。 在这个调试控制台内,不需要保存或者甚至实际上创建一个Lua模块,就可以执行Lua代码。


故障排除

 
使用可点击的“Script error”链接排除故障。

注意,红色的脚本错误消息是可点击的,且会提供详细信息。

Lua错误:内部错误:解释器已退出,状态为1。

When using the LuaStandalone engine (this is the default), errors along the lines of "Lua错误:内部错误:解释器已退出,状态为1。" may be generated if the standalone Lua interpreter cannot be executed or runs into various runtime errors. To obtain more information, assign a file path to $wgScribuntoEngineConf['luastandalone']['errorFile']. The interpreter's error output will be logged to the specified file, which should prove more helpful in tracking down the issue. The information in the debug log includes debugging information, which is why there is so much of it. You should be able to ignore any line beginning with "TX" or "RX".

If you're setting up Scribunto and are using IIS/Windows, this appears to be solved by commenting out a particular line.

Lua错误:内部错误:解释器已退出,状态为2。

When using the LuaStandalone engine (this is the default), status 2 suggests memory allocation errors, probably caused by settings that allocate inadequate memory space for PHP or Lua, or both. Assigning a file path to $wgScribuntoEngineConf['luastandalone']['errorFile'] and examining that output can be valuable in diagnosing memory allocation errors.

Increase PHP allocation in your PHP configuration; add the line memory_limit = 200M. This allocation of 200MB is often sufficient (as of MediaWiki 1.24) but can be increased as required. Set Scribunto's memory allocation in LocalSettings.php as a line:

$wgScribuntoEngineConf['luastandalone']['memoryLimit'] = 209715200; # bytes

Finally, depending on the server configuration, some installations may be helped by adding another LocalSettings.php line

$wgMaxShellMemory = 204800; # in KB

Note that all 3 memory limits are given in different units.

Lua error: Internal error: 2. on ARM architecture

If you're using an ARM architecture processor like on a RaspberryPi you'll face the error Lua error: Internal error: The interpreter exited with status 2. due to wrong delivered binary format of the Lua interpreter.

Check your Lua interpreter in:

/path/to/webdir/Scribunto/includes/engines/LuaStandalone/binaries/lua5_1_5_linux_32_generic

Check the interpreter by using:

file lua 

The result should look like :

lua: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0

The installed default Lua interpreter shows:

lua: ELF 32-bit LSB pie executable, Intel 80386, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux.so.2, for GNU/Linux 2.6.9,

look at the "Intel 80386" part what definitely is not correct.

Check in /usr/bin what version of Lua is installed on your system. If you have lua5.1 installed, you can either copy the interpreter to your lua5_1_5_linux_32_generic directory or set in your LocalSettings.php:

$wgScribuntoEngineConf['luastandalone']['luaPath'] = '/usr/bin/lua5.1'

At present don't set wgScribuntoEngineConf to /usr/bin/lua5.3, it'll lead to the "Internal error 1".

Lua错误:内部错误:解释器已退出,状态为24。

When using the LuaStandalone engine (this is the default), status 24 suggests CPU time limit errors, although those should be generating a "The time allocated for running scripts has expired" message instead. It would be useful to file a task in Phabricator and participate in determining why the XCPU signal isn't being caught.

Lua错误:内部错误:解释器已退出,状态为126。

When using the LuaStandalone engine (this is the default), errors along the lines of "Lua错误:内部错误:解释器已退出,状态为126。" may be generated if the standalone Lua interpreter cannot be executed. This generally arises from either of two causes:

  • The lua executable file's permissions do not include Execute.

Set permissions as described under #Installation.

  • The server does not allow execution of files from the place where the executable is installed, e.g. the filesystem is mounted with the 'noexec' flag.

This often occurs with shared hosted servers. Remedies include adjusting $wgScribuntoEngineConf['luastandalone']['luaPath'] to point to a Lua 5.1 binary installed in an executable location, or adjusting or convincing the shared host to adjust the setting preventing execution.

Error condition such as: Fatal exception of type MWException

Check the MediaWiki, PHP, or webserver logs for more details on the exception, or temporarily set $wgShowExceptionDetails to true.

version 'GLIBC_2.11' not found

If the above gives you errors such as "version 'GLIBC_2.11' not found", it means the version of the standard C library on your system is too old for the binaries provided with Scribunto. You should upgrade your C library, or use a version of Lua 5.1 compiled for the C library you do have installed. To upgrade your C library, your best option is usually to follow your distribution's instructions for upgrading packages (or for upgrading to a new release of the distribution, if applicable).

If you copy the lua binaries from Scribunto master (or from gerrit:77905), that should suffice, if you can't or don't want to upgrade your C library. The distributed binaries were recently recompiled against an older version of glibc, so the minimum is now 2.3 rather than 2.11.

Scribunto文件中的Lua错误

这里的错误包括:

  • attempt to index field 'text' (a nil value)(尝试访问'text'字段,其值为nil)
  • 位于mw.html.lua的253行的Lua错误:提供了无效类:

如果你在尝试使用从WMF wiki导入的模块时遇到此类错误,则很可能你的Scribunto版本已过期。

如有可能,请升级,对于高级用户,你可能需要找到需要的新提交,然后将其优选到你的本地安装中。

preg_replace_callback(): Compilation failed: unknown property name after \P or \p at offset 7

preg_replace_callback(): Compilation failed: unknown property name after \P or \p at offset 7

  • this usually indicates an incompatible version of PCRE; you'll need to update to >= 8.10
  • @todo: link to instructions on how to upgrade

Lua错误

如果你从维基百科复制模板,然后在Scribunto调用(例如,使用了{{#invoke:}}的模板)的位置收到大红色“Lua错误:x”的消息,这可能意味着你没有导入所需的所有内容。 确保在zh:Special:Export导出时勾选“包括模板”。

从另一个wiki导入页面时,导入数据中的模板或模块也可能覆盖具有相同标题的现有模板或模块,这可能会破坏依赖于覆盖版本的现有页面、模板和模块。

空白屏幕

确保你的扩展版本可以适用于你的MediaWiki版本。

设计文档

其他页面

参见

General
  • Lua Wikibase client - Scribunto扩展的功能。
  • Commons:Lua - 在Wikimedia Commons上可能有使用Lua模块的具体说明,包括安装的额外Lua扩展(例如,用于国际化的本地支持以及解析或播放媒体)。 一些通用模块可以在其他wiki中以各种语言重新使用(除了针对具有专用名称的方针、命名空间或项目/维护页面的特定调整)。 如果可能,应该在Wikimedia Commons上测试和国际化可以在wiki中广泛重新使用的模块。
  • w:Help:Lua - 维基百科可能有使用Lua模块的具体说明,包括安装的附加Lua扩展(包括用于集成维基数据和维基共享资源内容、生成复杂的信息框和导航框,或根据适用方针促进wiki内容的一般管理/维护)。 其他一些本地化的维基百科版本(或其他项目,如维基词典、维基共享资源或维基新闻)也可能有自己的需求和Lua模块。
  • d:Help:Lua - 可能会有关于在维基数据上使用Lua模块的具体说明,包括安装的额外Lua扩展(例如,用于国际化的本地支持和数据库查询)
Extensions

注释

  1. i.e. 如果服务器“php.ini”文件中的disable_functions数组中列出了proc_open,Scribunto将不起作用。 如果是,你可能收到像proc_open(): open_basedir restriction in effect. File(/dev/null) is not within the allowed path(s):这样的错误消息. 如果你正在使用Plesk且拥有了足够的权限,你也许能够在PHP设置中为你的域名或者子域名设置open_basedir。 尝试将{WEBSPACEROOT}{/}{:}{TMP}{/}更换成{WEBSPACEROOT}{/}{:}{TMP}{/}{:}/dev/null{:}/bin/bash