SSI 的指令及参数

Back to Documentation Index

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

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

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

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

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

1. Config 命令

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

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

   <!--#config errmsg="Error! Please email webmaster@mydomain.com -->

   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"-->

2. Include 命令

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

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

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

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

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

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

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

3. 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 文档中加入以下这行简单的文字，就可以在页面上动态的显示更新时间。

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

   除了 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"-->
4. Fsize 命令

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

   <!--#fsize file="index_working.html"-->
5. Flastmod 命令

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

   <!--#config timefmt="%A, the %d of %B, in the year %Y"-->
<!--#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"-->
<!--#config timefmt="%A, the %d of %B, in the year %Y"-->


   显示结果为：

   File April 19, 2000
Another File January 08, 2000

6. Exec 命令

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

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

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

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