在 nginx 中，`alias` 配合 `sub_filter` 替换响应文本的核心在于确保 `sub_filter` 指令被正确加载到处理静态文件的上下文中。具体做法是在定义 `location` 块并使用 `alias` 指定文件路径的同时，开启 `sub_filter` 并配置替换规则。需要注意的是，`sub_filter` 默认仅对 `text/html` 和 `text/xml` 生效，且必须显式设置 `sub_filter_types` 以覆盖其他类型（如 `application/javascript`）。此外，由于 `alias` 改变了 uri 到文件系统的映射路径，需确保替换的字符串与源文件中实际存在的文本完全一致，避免因路径或编码问题导致替换失败。
如何配置 location 块以实现基于路径的文本替换
要实现基于特定路径的文本替换，需要在 `server` 或 `location` 块中同时声明 `alias` 和 `sub_filter` 指令。`alias` 用于将 URL 路径映射到服务器上的实际目录，而 `sub_filter` 则在该位置处理的响应体中进行字符串查找和替换。关键在于这两个指令必须在同一个 `location` 块内生效，因为 `sub_filter` 是内容过滤模块，依赖于上游处理器生成的响应体。
server {
listen 80;
server_name example.com;
# 定义需要替换的路径
location /static/ {
# alias 指向实际的文件系统路径
alias /var/www/example/static/;
# 启用子过滤器
sub_filter_once off; # 替换所有匹配项，而非仅第一个
sub_filter 'old-text' 'new-text';
# 确保包含 JavaScript 等类型的响应
sub_filter_types application/javascript text/html;
# 可选：添加 Vary 头以支持缓存
add_header Vary "Accept-Encoding";
}
}
上述配置中，当请求 `/static/app.js` 时，Nginx 会去 `/var/www/example/static/app.js` 读取文件。如果文件内容包含 `old-text`，它将被替换为 `new-text`。`sub_filter_once off` 确保所有出现的文本都被替换，而不仅仅是第一次出现。`sub_filter_types` 明确指定了哪些 MIME 类型需要被处理，默认情况下只处理 HTML 和 XML，因此对于 JS 或 CSS 文件必须显式添加。
如何处理多文件批量替换及缓存一致性
当需要对多个文件或动态生成的内容进行批量替换时，`sub_filter` 的配置需要更加细致，特别是考虑到浏览器缓存的影响。如果替换后的内容与原始内容不同，但文件名未变，浏览器可能会使用旧的缓存版本。因此，除了配置替换规则外，还需要考虑缓存策略。此外，`sub_filter` 不支持正则表达式，只能进行精确的字符串匹配，这在处理复杂或多变的文本时需要特别注意。
# 假设有一个更复杂的场景，替换多个不同的字符串
location /api/data/ {
alias /var/www/example/api/;
# 多次调用 sub_filter 以替换多个不同的字符串
sub_filter 'status: true' 'status: active';
sub_filter 'status: false' 'status: inactive';
sub_filter 'version: 1.0' 'version: 2.0';
# 关闭一次性替换，确保所有实例都被替换
sub_filter_once off;
# 处理 JSON 响应
sub_filter_types application/json;
# 强制客户端重新验证缓存
add_header Cache-Control "no-cache, no-store, must-revalidate";
add_header Pragma "no-cache";
add_header Expires "0";
}
在这个例子中，我们展示了如何在一个 `location` 块中配置多个 `sub_filter` 指令，以替换不同的字符串组合。这对于 API 响应或动态生成的 JSON 数据非常有用。通过设置 `Cache-Control` 和 `Pragma` 头，我们确保客户端不会使用过时的缓存，从而保证替换后的内容能够立即生效。需要注意的是，`sub_filter` 的性能开销随着响应体大小的增加而增加，因此在高流量场景下应谨慎使用，或者考虑在应用层完成替换。
当 alias 指向的文件不存在时 sub_filter 的行为是什么
当 `alias` 指向的文件不存在时，Nginx 会返回 404 Not Found 错误，此时 `sub_filter` 不会执行任何操作，因为没有响应体可供过滤。这是预期的行为，因为 `sub_filter` 是一个输出过滤器，它只在成功获取资源后介入。如果希望在这种情况下提供自定义的错误页面并进行文本替换，需要在 `error_page` 指令中配置相应的处理逻辑，但这通常涉及更复杂的配置，如使用 `try_files` 或内部重定向。
