如何在Docker容器内访问主机localhost或避免硬编码IP

核心原因 #

Docker容器内的localhost指向容器自身，而非宿主机，所以直接用localhost:8080无法访问宿主机的API端点。以下是几种无需硬编码IP的解决方案：

方案1：利用Docker内置的主机别名（推荐跨平台） #

Docker提供了host.docker.internal内置别名用于指向宿主机，根据系统做少量配置即可：

步骤：

1. 修改docker-compose.yaml，添加环境变量和Linux系统所需的主机映射：

version: '3.8'

services:
  frontend:
    build:
      context: ./frontend
      target: development
    volumes:
      - ./frontend:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    environment:
      - NODE_ENV=development
      - VITE_API_URL=http://host.docker.internal:8080  # Vite环境变量需带VITE_前缀才能被前端读取
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux系统必须添加，Windows/macOS可省略

2. 在Svelte组件中读取环境变量并调用API：

const apiUrl = import.meta.env.VITE_API_URL;
fetch(`${apiUrl}/your-endpoint`)

方案2：配置Vite代理（开发环境最优） #

开发环境下通过Vite代理转发请求，前端代码无需关心实际API地址：

1. 在Svelte项目根目录修改vite.config.js：

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte()],
  server: {
    proxy: {
      // 匹配所有/api开头的请求，转发到宿主机API
      '/api': {
        target: 'http://host.docker.internal:8080',
        changeOrigin: true,
        // 若不需要保留/api前缀，可添加：rewrite: (path) => path.replace(/^\/api/, '')
      },
    },
  },
});

2. 前端直接用相对路径调用API：

fetch('/api/your-endpoint')

方案3：自定义Docker网络与固定别名 #

如果需要自定义主机别名，可通过自定义网络实现：

1. 修改docker-compose.yaml：

version: '3.8'

networks:
  app-network:
    driver: bridge

services:
  frontend:
    build:
      context: ./frontend
      target: development
    volumes:
      - ./frontend:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    environment:
      - NODE_ENV=development
      - VITE_API_URL=http://api-host:8080
    extra_hosts:
      - "api-host:host-gateway"  # 将api-host映射到宿主机网关
    networks:
      - app-network

2. 前端直接使用api-host别名访问API即可。

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