📄 mod_include.html
字号:
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312" />
<meta name="keywords" content="Apache, 中文, 手册, 中文版, 中文手册, 中文版手册, 参考手册, 中文参考手册, 金步国" />
<meta name="description" content="Apache 2.2 中文版参考手册" />
<meta name="author" content="金步国" />
<link href="../style/css/manual-zip.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-zip-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<title>mod_include － Apache 2.2 中文版参考手册</title>
</head>
<body><div id="page-header">
<p class="menu"><a href="../mod/index.html">模块索引</a> | <a href="../mod/directives.html">指令索引</a> | <a href="../faq/index.html">常见问题</a> | <a href="../glossary.html">词汇表</a> | <a href="../sitemap.html">站点导航</a></p><p class="apache">Apache HTTP Server 版本2.2</p><img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./index.html"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">文档</a> > <a href="../index.html">版本2.2</a> > <a href="./index.html">模块</a></div>
<div id="translation-info"> <a href="../translator_announcement.html#thanks">致谢</a> | <a href="../translator_announcement.html#announcement">译者声明</a> | 本篇译者：<<a href="../translator_announcement.html#join">虚位以待</a>> | 本篇译稿完成时间：?年?月?日 | <a href="../translator_announcement.html#last_new">获取最新版本</a></div>
<div id="page-content"><div id="preamble"><h1>Apache模块 mod_include</h1>
<table border="1" cellpadding="0" cellspacing="0" bordercolor="#AAAAAA" class="module">
<tr><th><a href="module-dict.html#Description">说明</a></th><td>实现服务端包含文档(SSI)处理</td></tr>
<tr><th><a href="module-dict.html#Status">状态</a></th><td>基本(B)</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">模块名</a></th><td>include_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">源文件</a></th><td>mod_include.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">兼容性</a></th><td>Implemented as an output filter since Apache
2.0</td></tr>
</table>
<h3>概述</h3>
<p>This module provides a filter which will process files
before they are sent to the client. The processing is
controlled by specially formatted SGML comments, referred to as
<dfn>elements</dfn>. These elements allow conditional text, the
inclusion of other files or programs, as well as the setting and
printing of environment variables.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></h2>
<p>Server Side Includes are implemented by the
<code>INCLUDES</code> <a href="../filter.html">filter</a>. If
documents containing server-side include directives are given
the extension .shtml, the following directives will make Apache
parse them and assign the resulting document the mime type of
<code>text/html</code>:</p>
<div class="example"><p><code>
AddType text/html .shtml<br />
AddOutputFilter INCLUDES .shtml
</code></p></div>
<p>The following directive must be given for the directories
containing the shtml files (typically in a
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section,
but this directive is also valid in <code>.htaccess</code> files if
<code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
is set):</p>
<div class="example"><p><code>
Options +Includes
</code></p></div>
<p>For backwards compatibility, the <code>server-parsed</code>
<a href="../handler.html">处理器</a> also activates the
INCLUDES filter. As well, Apache will activate the INCLUDES
filter for any document with mime type
<code>text/x-server-parsed-html</code>或<code>text/x-server-parsed-html3</code> (and the resulting
output will have the mime type <code>text/html</code>).</p>
<p>For more information, see our <a href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
<p>Files processed for server-side includes no longer accept
requests with <code>PATH_INFO</code> (trailing pathname information)
by default. You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
configure the server to accept requests with <code>PATH_INFO</code>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="elements" id="elements">Basic Elements</a></h2>
<p>The document is parsed as an HTML document, with special
commands embedded as SGML comments. A command has the syntax: </p>
<div class="example"><p><code>
<!--#<var>element</var> <var>attribute</var>=<var>value</var>
<var>attribute</var>=<var>value</var> ... -->
</code></p></div>
<p>The value will often be enclosed in double quotes, but single
quotes (<code>'</code>) and backticks (<code>`</code>) are also
possible. Many commands only allow a single attribute-value pair.
Note that the comment terminator (<code>--></code>) should be
preceded by whitespace to ensure that it isn't considered part of
an SSI token. Note that the leading <code><!--#</code> is <em>one</em>
token and may not contain any whitespaces.</p>
<p>The allowed elements are listed in the following table:</p>
<table border="1" cellpadding="0" cellspacing="0" bordercolor="#AAAAAA" class="bordered">
<tr><th>Element</th><th>Description</th></tr>
<tr><td><code><a href="#element.config">config</a></code></td><td>configure output formats</td></tr>
<tr><td><code><a href="#element.echo">echo</a></code></td><td>print variables</td></tr>
<tr><td><code><a href="#element.exec">exec</a></code></td><td>execute external programs</td></tr>
<tr><td><code><a href="#element.fsize">fsize</a></code></td><td>print size of a file</td></tr>
<tr><td><code><a href="#element.flastmod">flastmod</a></code></td><td>print last modification time of a file</td></tr>
<tr><td><code><a href="#element.include">include</a></code></td><td>include a file</td></tr>
<tr><td><code><a href="#element.printenv">printenv</a></code></td><td>print all available variables</td></tr>
<tr><td><code><a href="#element.set">set</a></code></td><td>set a value of a variable</td></tr>
</table>
<p>SSI elements may be defined by modules other than
<code class="module"><a href="../mod/mod_include.html">mod_include</a></code>. In fact, the <code><a href="#element.exec">exec</a></code> element is provided by
<code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
module is loaded.</p>
<h3><a name="element.config" id="element.config">The config Element</a></h3>
<p>This command controls various aspects of the parsing. The
valid attributes are:</p>
<dl>
<dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
<dd>The value is a message that is sent back to the
client if the <code><a href="#element.echo">echo</a></code> element
attempts to echo an undefined variable. This overrides any <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directives.</dd>
<dt><code>errmsg</code></dt>
<dd>The value is a message that is sent back to the
client if an error occurs while parsing the
document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</dd>
<dt><code>sizefmt</code></dt>
<dd>The value sets the format to be used which displaying
the size of a file. Valid values are <code>bytes</code>
for a count in bytes, or <code>abbrev</code> for a count
in Kb or Mb as appropriate, for example a size of 1024 bytes
will be printed as "1K".</dd>
<dt><code>timefmt</code></dt>
<dd>The value is a string to be used by the
<code>strftime(3)</code> library routine when printing
dates.</dd>
</dl>
<h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
<p>This command prints one of the <a href="#includevars">include
variables</a>, defined below. If the variable is unset, the result is
determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
subject to the currently configured <code>timefmt</code>.</p>
<p>Attributes:</p>
<dl>
<dt><code>var</code></dt>
<dd>The value is the name of the variable to print.</dd>
<dt><code>encoding</code></dt>
<dd><p>Specifies how Apache should encode special characters
contained in the variable before outputting them. If set
to <code>none</code>, no encoding will be done. If set to
<code>url</code>, then URL encoding (also known as %-encoding;
this is appropriate for use within URLs in links, etc.) will be
performed. At the start of an <code>echo</code> element,
the default is set to <code>entity</code>, resulting in entity
encoding (which is appropriate in the context of a block-level
HTML element, 例如， a paragraph of text). This can be
changed by adding an <code>encoding</code> attribute, which will
remain in effect until the next <code>encoding</code> attribute
is encountered or the element ends, whichever comes first.</p>
<p><code>encoding</code> attribute must <em>precede</em> the
corresponding <code>var</code> attribute to be effective, and
only special characters as defined in the ISO-8859-1 character
encoding will be encoded. This encoding process may not have the
desired result if a different character encoding is in use.</p>
<div class="warning">
In order to avoid cross-site scripting issues, you should
<em>always</em> encode user supplied data.
</div>
</dd>
</dl>
<h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
<p><code>exec</code> command executes a given shell command or
CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
<code>IncludesNOEXEC</code> is set, this command is completely
disabled. The valid attributes are:</p>
<dl>
<dt><code>cgi</code></dt>
<dd><p>The value specifies a (%-encoded) URL-path to
the CGI script. If the path does not begin with a slash (/),
then it is taken to be relative to the current
document. The document referenced by this path is
invoked as a CGI script, even if the server would not
normally recognize it as such. However, the directory
containing the script must be enabled for CGI scripts
(with <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>或<code class="directive"><a href="../mod/core.html#options">Options</a></code>
<code>ExecCGI</code>).</p>
<p>The CGI script is given the <code>PATH_INFO</code> and query
string (<code>QUERY_STRING</code>) of the original request from the
client; these <em>cannot</em> be specified in the URL path. The
include variables will be available to the script in addition to
the standard <a href="mod_cgi.html">CGI</a> environment.</p>
<div class="example"><h3>示例</h3><p><code>
<!--#exec cgi="/cgi-bin/example.cgi" -->
</code></p></div>
<p>If the script returns a <code>Location:</code> header instead of
output, then this will be translated into an HTML anchor.</p>
<p><code><a href="#includevirtual">include virtual</a></code>
element should be used in preference to <code>exec cgi</code>. In
particular, if you need to pass additional arguments to a CGI program,
using the query string, this cannot be done with <code>exec
cgi</code>, but can be done with <code>include virtual</code>, as
shown here:</p>
<div class="example"><p><code>
<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
</code></p></div>
</dd>
<dt><code>cmd</code></dt>
<dd><p>The server will execute the given string using
<code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
to the usual set of CGI variables.</p>
<p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
either <code>#exec cgi</code>或<code>#exec cmd</code>. The former
(<code>#include virtual</code>) uses the standard Apache sub-request
mechanism to include files or scripts. It is much better tested and
maintained.</p>
<p>In addition, on some platforms, like Win32, and on unix when
using <a href="../suexec.html">suexec</a>, you cannot pass arguments
to a command in an <code>exec</code> directive, or otherwise include
spaces in the command. Thus, while the following will work under a
non-suexec configuration on unix, it will not produce the desired
result under Win32, or when running suexec:</p>
<div class="example"><p><code>
<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
</code></p></div>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -