Nginx 托管 Vue 项目指南：配置 sub_filter 解决跨域接口注入-Nginx-PHP中文网

Vue打包后可用Nginx托管，通过sub_filter模块在HTML中将占位符“__API_BASE__”动态替换为真实API地址，解决跨域问题；需确认Nginx启用sub_filter模块，配置sub_filter_once off和sub_filter_types text/html，并注意替换唯一性与安全性。

nginx 托管 vue 项目指南：配置 sub_filter 解决跨域接口注入

Vue 项目打包后是纯静态文件，Nginx 直接托管即可。但生产环境常遇到接口跨域问题——后端 API 域名与前端页面域名不一致，浏览器报 CORS 错误。直接改后端 Access-Control-Allow-Origin 不总是可行（比如第三方接口、多环境混用），这时可利用 Nginx 的 sub_filter 模块，在 HTML 响应体中动态替换接口地址，把相对路径或占位符“注入”为真实 API 地址，绕过浏览器同源限制。

确认 Nginx 已启用 sub_filter 模块

sub_filter 是 Nginx 的标准 HTTP 模块，但默认不编译进某些精简版（如 Alpine 官方镜像或部分系统包）。运行以下命令验证：

nginx -V 2>&1 | grep -o with-http_sub_module

若无输出，需重新编译 Nginx 或换用含该模块的发行版（如 Ubuntu/Debian 官方源、nginx:alpine（较新版本）或 nginx:mainline 镜像）。

Vue 项目中预留可替换的 API 占位符

不要在代码里硬写 https://api.example.com。推荐两种方式：

在 public/index.html 中插入一个全局变量，例如：
<script>window.__API_BASE__ = '__API_BASE__';</script>
或在请求封装层（如 src/utils/request.js）中统一使用字符串占位符：
axios.defaults.baseURL = '__API_BASE__';

构建时保持该字符串原样输出（Vue CLI 默认不会替换 public/ 下内容，且 Webpack/Vite 对 JS 字符串不做预处理）。

Nginx 配置 sub_filter 替换占位符

在 server 块中添加如下配置（注意顺序和作用域）：

location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html;

# 启用 sub_filter，仅对 text/html 生效
sub_filter '__API_BASE__' 'https://api.yourdomain.com';
sub_filter_once off;
sub_filter_types text/html;
}

关键点说明：

sub_filter_once off：允许多次替换（否则只替换第一个匹配项）
sub_filter_types text/html：明确指定处理类型；若页面含内联 JS，也可加 application/javascript，但需确保响应头 Content-Type 匹配
替换必须在 try_files 后生效，因此放在 location 主体内，而非嵌套在 if 或其他指令中
若使用 gzip，需加 sub_filter_last_modified off; 并确保 gzip_vary off;，避免缓存干扰

进阶：多环境支持与安全注意事项

可通过 Nginx 变量或 map 指令实现环境区分：

map $host $api_base {
~^staging\. example\.com$ https://api-staging.example.com;
default https://api-prod.example.com;
}

location / {
...
sub_filter '__API_BASE__' $api_base;
}

安全提醒：