SSI 的指令及参数

SSI 在使用时遵循以下格式：

<!--#directive parameter="value"-->

其中，directive 是向服务器发送的指令名称，parameter 是指令的操作对象，而 value 则是用户希望得到的指令处理结果。

所有的 SSI 命令都是以 "<!--#" 开始，其中 "<!-" 和 "#" 之间不能有任何空格，否则服务器会把 SSI 命令当称普通的文件注释处理，不会显示出任何结果，也不会产生错误提示。此外，SSI 命令中的 "=" 两边不能有空格，右边的值必须包含在双引号内，后面可以跟空格，最后是结束标签 "-->"。

SSI 命令包含六大类指令以及各自的参数，具体如下：

指令及参数

指令名称 参数列表

Config errmsg, timefmt, sizefmt

include virtual, file

echo var

fsize file

flastmod file

exec cmd, cgi

下面我们将逐一进行介绍。

Config 命令

Config 命令主要用于修改 SSI 的默认设置。其中：

Errmsg：设置默认错误信息。为了能够正常的返回用户设定的错误信息，在 HTML 文件中 Errmsg 参数必须被放置在其它 SSI 命令的前面，否则客户端只能显示默认的错误信息，而不是由用户设定的自定义信息。

<!--#config errmsg="Error! Please email [email protected] -->

Timefmt：定义日期和时间的使用格式。Timefmt 参数必须在 echo 命令之前使用。

<!--#config timefmt="%A, %B %d, %Y"-->

<!--#echo var="LAST_MODIFIED"-->

显示结果为：

Wednesday, April 12, 2000

也许用户对上例中所使用的 %A %B %d 感到很陌生，下面我们就以表格的形式总结一下 SSI 中较为常用的一些日期和时间格式。

Sizefmt：决定文件大小是以字节、千字节还是兆字节为单位表示。如果以字节为单位，参数值为 "bytes"；对于千字节和兆字节可以使用缩写形式。同样，sizefmt 参数必须放在 fsize 命令的前面才能使用。

<!--#config sizefmt="bytes"-->

<!--#fsize file="index.html"-->

Include 命令

Include 命令可以把其它文档中的文字或图片插入到当前被解析的文档中，这是整个 SSI 的关键所在。通过 Include 命令只需要改动一个文件就可以瞬间更新整个站点！

Include 命令具有两个不同的参数：

Virtual：给出到服务器端某个文档的虚拟路径。例如：

<!--#include virtual="/includes/header.html"-->

File：给出到当前目录的相对路径，其中不能使用 "../"，也不能使用绝对路径。例如：

<!--#include file="header.html"-->

这就要求每一个目录中都包含一个 header.html 文件。

Echo 命令

Echo 命令可以显示以下各环境变量：

DOCUMENT_NAME：显示当前文档的名称。

<!--#echo var="DOCUMENT_NAME"-->

index.html

DOCUMENT_URI：显示当前文档的虚拟路径。例如：

<!--#echo var="DOCUMENT_URI"-->

/YourDirectory/YourFilename.html

随着网站的不断发展，那些越来越长的 URL 地址肯定会让人头疼。如果使用 SSI，一切就会迎刃而解。因为我们可以把网站的域名和 SSI 命令结合在一起显示完整的 URL，即：

http://YourDomain<!--#echo var="DOCUMENT_URI"-->

QUERY_STRING_UNESCAPED：显示未经转义处理的由客户端发送的查询字串，其中所有的特殊字符前面都有转义符 "\"。例如：

<!--#echo var="QUERY_STRING_UNESCAPED"-->

DATE_LOCAL：显示服务器设定时区的日期和时间。用户可以结合 config 命令的 timefmt 参数，定制输出信息。例如：

<!--#config timefmt="%A, the %d of %B, in the year %Y"-->

<!--#echo var="DATE_LOCAL"-->

Saturday, the 15 of April, in the year 2000

DATE_GMT：功能与 DATE_LOCAL 一样，只不过返回的是以格林尼治标准时间为基准的日期。例如：

<!--#echo var="DATE_GMT"-->

LAST_MODIFIED：显示当前文档的最后更新时间。同样，这是 SSI 中非常实用的一个功能，只要在 HTML 文档中加入以下这行简单的文字，就可以在页面上动态的显示更新时间。

除了 SSI 环境变量之外，echo 命令还可以显示以下 CGI 环境变量：

SERVER_SOFTWARE：显示服务器软件的名称和版本。例如：

<!--#echo var="SERVER_SOFTWARE"-->

SERVER_NAME：显示服务器的主机名称，DNS 别名或 IP 地址。例如：

<!--#echo var="SERVER_NAME"-->

SERVER_PROTOCOL：显示客户端请求所使用的协议名称和版本，如 HTTP/1.0。例如：

<!--#echo var="SERVER_PROTOCOL"-->

SERVER_PORT：显示服务器的响应端口。例如：

<!--#echo var="SERVER_PORT"-->

REQUEST_METHOD：显示客户端的文档请求方法，包括 GET，HEAD，和 POST。例如：

<!--#echo var="REQUEST_METHOD"-->

REMOTE_HOST：显示发出请求信息的客户端主机名称。

<!--#echo var="REMOTE_HOST"-->

REMOTE_ADDR：显示发出请求信息的客户端IP地址。

<!--#echo var="REMOTE_ADDR"-->

AUTH_TYPE：显示用户身份的验证方法。

<!--#echo var="AUTH_TYPE"-->

REMOTE_USER：显示访问受保护页面的用户所使用的帐号名称。

<!--#echo var="REMOTE_USER"-->

Fsize 命令

Fsize 显示指定文件的大小，可以结合 config 命令的 sizefmt 参数定制输出格式。

<!--#fsize file="index_working.html"-->

Flastmod 命令

Flastmod 显示指定文件的最后修改日期，可以结合 config 命令的 timefmt 参数控制输出格式。

<!--#flastmod file="file.html"-->

这里，我们可以利用 flastmod 参数显示出一个页面上所有链接页面的更新日期。方法如下：

<!--#config timefmt=" %B %d, %Y"-->

<A HREF="/directory/file.html">File</A>

<!--#flastmod virtual="/directory/file.html"-->

<A HREF="/another_directory/another_file.html">Another File</A>

<!--#flastmod virtual="/another_directory/another_file.html"-->

File April 19, 2000

Another File January 08, 2000

Exec 命令

Exec 命令可以执行 CGI 脚本或者 shell 命令。使用方法如下：

Cmd：使用 /bin/sh 执行指定的字串。如果 SSI 使用了 IncludesNOEXEC 选项，则该命令将被屏蔽。

Cgi：可以用来执行 CGI 脚本。例如，下面这个例子中使用服务端 cgi-bin 目录下的 counter.pl 脚本程序在每个页面放置一个计数器：

<!--#exec cgi="/cgi-bin/counter.pl"-->