Next.js静态HTML导出应用构建后变量配置方案咨询

针对静态导出的Next.js应用用Docker+Nginx部署，构建后需要修改变量的场景，以下是几种可行方案：

方案1：使用envsubst替换静态文件占位符 #

核心思路是构建阶段将可变变量替换为占位符，镜像启动时用环境变量替换这些占位符，再启动Nginx。

步骤：

1. 静态导出时设置占位符：在Next.js代码中，将需要动态配置的变量用占位符标记，比如：

   // 替换硬编码的API地址为占位符
   const apiUrl = process.env.NEXT_PUBLIC_API_URL || '${API_URL}';
   

   执行next export后，静态文件（HTML/JS/CSS）中会保留${API_URL}这类占位符。

2. Docker镜像中加入替换逻辑：

   • 安装gettext工具（包含envsubst命令）
   • 编写启动脚本，替换所有静态文件中的占位符后启动Nginx

   示例Dockerfile片段：

   FROM nginx:alpine
   # 安装gettext
   RUN apk add --no-cache gettext
   # 复制静态导出文件到Nginx目录
   COPY out/ /usr/share/nginx/html/
   # 复制启动脚本
   COPY start-nginx.sh /usr/local/bin/
   RUN chmod +x /usr/local/bin/start-nginx.sh
   # 执行启动脚本
   CMD ["start-nginx.sh"]
   

   启动脚本start-nginx.sh内容：

   #!/bin/sh
   # 替换所有静态文件中的API_URL占位符
   find /usr/share/nginx/html -type f \( -name "*.html" -o -name "*.js" -o -name "*.css" \) -exec sed -i "s|\${API_URL}|${API_URL:-https://default.api.com}|g" {} \;
   # 启动Nginx
   nginx -g 'daemon off;'
   

3. 启动镜像时传递环境变量：

   docker run -e API_URL=https://prod.api.com -p 80:80 your-image-name
   

方案2：抽离可变配置为独立JSON文件 #

将需要动态修改的配置单独放在一个JSON文件中，应用运行时异步加载该文件，构建后只需替换或生成这个文件即可。

步骤：

1. 应用中添加配置加载逻辑：

   // utils/config.js
   export async function fetchConfig() {
     const response = await fetch('/config.json');
     return response.json();
   }
   

   在组件中使用：

   import { fetchConfig } from '../utils/config';
   
   async function HomePage() {
     const config = await fetchConfig();
     return <div>当前API地址：{config.apiUrl}</div>;
   }
   
   export default HomePage;
   

2. Docker中配置动态生成JSON文件：
   编写启动脚本，从环境变量生成config.json后启动Nginx：

   #!/bin/sh
   # 生成config.json
   cat > /usr/share/nginx/html/config.json << EOF
   {
     "apiUrl": "${API_URL:-https://default.api.com}",
     "appTitle": "${APP_TITLE:-My App}"
   }
   EOF
   # 启动Nginx
   nginx -g 'daemon off;'
   

3. 启动时传递变量：

   docker run -e API_URL=https://prod.api.com -e APP_TITLE=Production App -p 80:80 your-image-name
   

   也可以通过挂载外部的config.json文件直接替换：

   docker run -v ./prod-config.json:/usr/share/nginx/html/config.json -p 80:80 your-image-name
   

方案3：使用Nginx sub_filter模块动态替换响应 #

利用Nginx的sub_filter模块，在返回响应给客户端时动态替换内容中的占位符，无需修改应用代码。

步骤：

1. 静态导出时设置占位符：在Next.js代码中使用固定占位符，比如：

   const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'PLACEHOLDER_API_URL';
   

2. 配置Nginx启用sub_filter：
   创建Nginx配置模板default.conf.template：

   server {
     listen 80;
     root /usr/share/nginx/html;
     index index.html;
   
     location / {
       try_files $uri $uri/ /index.html;
       # 替换占位符为环境变量
       sub_filter 'PLACEHOLDER_API_URL' '$API_URL';
       sub_filter_once off; # 替换所有匹配项
     }
   }
   

3. Dockerfile中处理Nginx配置：

   FROM nginx:alpine
   COPY out/ /usr/share/nginx/html/
   COPY default.conf.template /etc/nginx/conf.d/
   # 启动时用envsubst替换Nginx配置中的环境变量，再启动Nginx
   CMD envsubst '$API_URL' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'
   

4. 启动镜像时传递变量：

   docker run -e API_URL=https://prod.api.com -p 80:80 your-image-name
   

内容的提问来源于stack exchange，提问作者Gokhan Sari