windows-git-bash-paths

🚨 关键指南

Windows 文件路径要求

强制要求：在 Windows 上始终使用反斜杠表示文件路径

在 Windows 上使用 Edit 或 Write 工具时，文件路径必须使用反斜杠（\），而不是正斜杠（/）。

示例：

• ❌ 错误：D:/repos/project/file.tsx
• ✅ 正确：D:\repos\project\file.tsx

此要求适用于：

• Edit 工具的 file_path 参数
• Write 工具的 file_path 参数
• Windows 系统上的所有文件操作

文档指南

除非用户明确要求，否则绝不创建新的文档文件。

• 优先事项：更新现有的 README.md 文件，而不是创建新文档
• 保持代码库整洁：保持代码库根目录整洁——除非用户另有要求，否则只保留 README.md
• 风格：文档应简洁、直接且专业——避免使用 AI 生成式语气
• 用户偏好：只有在用户明确要求编写文档时，才创建其他 .md 文件

---

SSDT 的 Windows 和 Git Bash 路径处理

概述

SQL Server 开发主要在 Windows 上进行，许多开发者在 Windows 上使用 Git Bash（MINGW/MSYS2）作为首选 shell。这会带来独特的路径转换问题，因为 SqlPackage、MSBuild 和 Visual Studio 等 Windows 原生工具需要 Windows 风格的路径。

本指南全面介绍了在 Windows 上使用 Git Bash 处理路径转换问题、检测 shell 以及遵循 SSDT 工作流最佳实践的方法。

路径转换问题

Git Bash/MINGW 中会发生什么

Git Bash 会自动将 POSIX 风格的路径转换为 Windows 路径，但这可能导致命令行参数出现问题：

自动转换：

• /foo → C:/Program Files/Git/usr/foo
• /foo:/bar → C:\msys64\foo;C:\msys64\bar
• --dir=/foo → --dir=C:/msys64/foo

对 SqlPackage 的影响：

# Git Bash converts /Action to a path!
sqlpackage /Action:Publish /SourceFile:MyDB.dacpac
# Becomes: sqlpackage C:/Program Files/Git/usr/Action:Publish ...

会触发转换的情况

✓ 参数以正斜杠（/）开头 ✓ 以冒号分隔的路径列表 ✓ - 或 , 后面带有路径组件的参数

不受影响的情况

✓ 包含 = 的参数（变量赋值） ✓ 驱动器标识符（C:） ✓ 包含 ; 的参数（已是 Windows 格式） ✓ 以 // 开头的参数（Windows 开关）

在 Git Bash 中使用 SqlPackage 的解决方案

方法 1：MSYS_NO_PATHCONV（推荐）

为特定命令禁用路径转换：

# Temporarily disable path conversion
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDatabase.dacpac" \
  /TargetServerName:"localhost" \
  /TargetDatabaseName:"MyDB"

# Works for all SqlPackage actions
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  /TargetFile:"MyDB_backup.dacpac"

重要说明：

• VALUE 的值无关紧要——设为 0、false 或空值仍会禁用转换
• 关键在于该变量已定义
• 如需重新启用：env -u MSYS_NO_PATHCONV

方法 2：双斜杠 //（替代方案）

在 SqlPackage 参数中使用双斜杠：

# Works in Git Bash and CMD
sqlpackage //Action:Publish \
  //SourceFile:MyDatabase.dacpac \
  //TargetServerName:localhost \
  //TargetDatabaseName:MyDB

# Extract with double slashes
sqlpackage //Action:Extract \
  //SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  //TargetFile:output.dacpac

优点：

• 无需环境变量
• 适用于各种 shell
• 脚本与 shell 无关

方法 3：使用带引号的 Windows 风格路径

始终将带反斜杠的路径括在引号中：

# Quoted Windows paths work in Git Bash
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:\Projects\MyDB\bin\Release\MyDB.dacpac" \
  /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

# Or with forward slashes (Windows accepts both)
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac" \
  /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

方法 4：切换到 PowerShell 或 CMD

对于 Windows 原生工具，可考虑使用原生 shell：

# PowerShell (recommended for Windows SSDT workflows)
sqlpackage /Action:Publish `
  /SourceFile:"MyDatabase.dacpac" `
  /TargetServerName:"localhost" `
  /TargetDatabaseName:"MyDB"

:: CMD
sqlpackage /Action:Publish ^
  /SourceFile:"MyDatabase.dacpac" ^
  /TargetServerName:"localhost" ^
  /TargetDatabaseName:"MyDB"

脚本中的 Shell 检测

Bash 脚本检测

#!/bin/bash

# Method 1: Check $OSTYPE
case "$OSTYPE" in
  msys*)       # MSYS/Git Bash/MinGW
    export MSYS_NO_PATHCONV=1
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  cygwin*)     # Cygwin
    export MSYS_NO_PATHCONV=1
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  linux-gnu*)  # Linux
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  darwin*)     # macOS
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
esac

sqlpackage $SQLPACKAGE_ARGS

# Method 2: Check uname -s (most portable)
case "$(uname -s)" in
  MINGW64*|MINGW32*)
    # Git Bash
    export MSYS_NO_PATHCONV=1
    echo "Git Bash detected - path conversion disabled"
    ;;
  MSYS_NT*)
    # MSYS
    export MSYS_NO_PATHCONV=1
    echo "MSYS detected - path conversion disabled"
    ;;
  CYGWIN*)
    # Cygwin
    export MSYS_NO_PATHCONV=1
    echo "Cygwin detected - path conversion disabled"
    ;;
  Linux*)
    # Linux or WSL
    echo "Linux detected"
    ;;
  Darwin*)
    # macOS
    echo "macOS detected"
    ;;
esac

# Method 3: Check $MSYSTEM (Git Bash specific)
if [ -n "$MSYSTEM" ]; then
  # Running in Git Bash/MSYS2
  export MSYS_NO_PATHCONV=1
  echo "MSYS environment detected: $MSYSTEM"
  case "$MSYSTEM" in
    MINGW64) echo "64-bit native Windows environment" ;;
    MINGW32) echo "32-bit native Windows environment" ;;
    MSYS)    echo "POSIX-compliant environment" ;;
  esac
fi

完整构建脚本示例

#!/bin/bash
# build-and-deploy.sh - Cross-platform SSDT build script

set -e  # Exit on error

# Detect shell and set path conversion
if [ -n "$MSYSTEM" ]; then
  echo "Git Bash/MSYS2 detected - disabling path conversion"
  export MSYS_NO_PATHCONV=1
fi

# Variables
PROJECT_NAME="MyDatabase"
BUILD_CONFIG="Release"
DACPAC_PATH="bin/${BUILD_CONFIG}/${PROJECT_NAME}.dacpac"
TARGET_SERVER="${SQL_SERVER:-localhost}"
TARGET_DB="${SQL_DATABASE:-MyDB}"

# Build
echo "Building ${PROJECT_NAME}..."
dotnet build "${PROJECT_NAME}.sqlproj" -c "$BUILD_CONFIG"

# Verify DACPAC exists
if [ ! -f "$DACPAC_PATH" ]; then
  echo "ERROR: DACPAC not found at $DACPAC_PATH"
  exit 1
fi

echo "DACPAC built successfully: $DACPAC_PATH"

# Deploy
echo "Deploying to ${TARGET_SERVER}/${TARGET_DB}..."

# Use double-slash method for maximum compatibility
sqlpackage //Action:Publish \
  //SourceFile:"$DACPAC_PATH" \
  //TargetServerName:"$TARGET_SERVER" \
  //TargetDatabaseName:"$TARGET_DB" \
  //p:BlockOnPossibleDataLoss=False

echo "Deployment complete!"

Git Bash 中常见的 SSDT 路径问题

问题 1：DACPAC 文件路径

问题：

# Git Bash mangles the path
sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac
# Error: Cannot find file

解决方案：

# Use MSYS_NO_PATHCONV
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"./bin/Release/MyDB.dacpac"

# OR use absolute Windows path
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac"

# OR use double slashes
sqlpackage //Action:Publish //SourceFile:./bin/Release/MyDB.dacpac

问题 2：SQL 项目文件路径

问题：

# Path with spaces causes issues
dotnet build "D:/Program Files/MyProject/Database.sqlproj"
# Works in Git Bash (dotnet handles paths correctly)

# But MSBuild paths may fail
msbuild "D:/Program Files/MyProject/Database.sqlproj"
# May fail if not quoted properly

解决方案：

# Always quote paths with spaces
dotnet build "D:/Program Files/MyProject/Database.sqlproj"

# Use backslashes for MSBuild on Windows
msbuild "D:\Program Files\MyProject\Database.sqlproj"

# Or use 8.3 short names (no spaces)
msbuild "D:/PROGRA~1/MyProject/Database.sqlproj"

问题 3：发布配置文件路径

问题：

# Publish profile not found
sqlpackage /Action:Publish \
  /SourceFile:MyDB.dacpac \
  /Profile:./Profiles/Production.publish.xml

解决方案：

# Use MSYS_NO_PATHCONV with quoted paths
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDB.dacpac" \
  /Profile:"./Profiles/Production.publish.xml"

# Or absolute Windows path
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB.dacpac" \
  /Profile:"D:/Projects/Profiles/Production.publish.xml"

问题 4：连接字符串

问题：

# File paths in connection strings
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:/Data/MyDB.mdf"
# Path gets mangled

解决方案：

# Quote entire connection string
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\Data\MyDB.mdf" \
  /TargetFile:"output.dacpac"

# Or use double backslashes in connection string
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\\Data\\MyDB.mdf"

CI/CD 注意事项

使用 Git Bash 的 GitHub Actions

name: SSDT Build and Deploy

on: [push]

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: bash  # Use Git Bash

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install SqlPackage
        run: dotnet tool install -g Microsoft.SqlPackage

      - name: Build Database Project
        run: dotnet build Database.sqlproj -c Release

      - name: Deploy with Path Conversion Disabled
        env:
          MSYS_NO_PATHCONV: 1
        run: |
          sqlpackage /Action:Publish \
            /SourceFile:"bin/Release/MyDatabase.dacpac" \
            /TargetServerName:"localhost" \
            /TargetDatabaseName:"MyDB"

PowerShell 替代方案（Windows 上推荐）

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: pwsh  # Use PowerShell - no path issues

    steps:
      - name: Deploy Database
        run: |
          sqlpackage /Action:Publish `
            /SourceFile:"bin/Release/MyDatabase.dacpac" `
            /TargetServerName:"localhost" `
            /TargetDatabaseName:"MyDB"

最佳实践总结

交互式开发

1. 在 Windows 上使用 PowerShell 或 CMD 进行 SSDT 开发——完全避免路径转换问题
2. 如果使用 Git Bash，在 shell 配置文件中将 MSYS_NO_PATHCONV=1 设置为 SSDT 工作环境变量
3. 始终为路径加引号，尤其是包含空格或特殊字符的路径
4. 尽可能使用绝对路径，以免产生歧义

针对脚本

1. 检测 shell 环境，并有条件地设置 MSYS_NO_PATHCONV=1
2. SqlPackage 参数使用双斜杠 // 语法（兼容性最好）
3. Windows 专属工作流优先使用 PowerShell（构建脚本、CI/CD）
4. 在所有目标平台上测试脚本（Windows PowerShell、Git Bash、Linux）

针对 CI/CD

1. 对于 Windows 运行器，在 GitHub Actions 中使用 PowerShell shell（shell: pwsh）
2. 自托管的 Windows Agent——使用原生 Windows 路径和 shell
3. 如果必须使用 Git Bash，将 MSYS_NO_PATHCONV=1 设为环境变量
4. 跨平台兼容性方面优先使用 dotnet CLI，而非 MSBuild

针对团队

1. 在代码库 README 中记录 shell 要求
2. 为所有 shell 提供脚本（bash、PowerShell、CMD）
3. 在可能的情况下，Windows SSDT 工作流统一使用 PowerShell
4. 使用容器化构建，避免 shell 特有的问题

快速参考

环境变量

# Disable path conversion (Git Bash/MSYS2/Cygwin)
export MSYS_NO_PATHCONV=1

# Re-enable path conversion
env -u MSYS_NO_PATHCONV

SqlPackage 命令模板

# Git Bash - Method 1 (MSYS_NO_PATHCONV)
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

# Git Bash - Method 2 (Double Slash)
sqlpackage //Action:Publish //SourceFile:MyDB.dacpac //TargetServerName:localhost //TargetDatabaseName:MyDB

# PowerShell (Recommended for Windows)
sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

# CMD
sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

Shell 检测单行命令

# Check if Git Bash/MSYS
[ -n "$MSYSTEM" ] && echo "Git Bash/MSYS2 detected"

# Check uname
[[ "$(uname -s)" =~ ^MINGW ]] && echo "Git Bash detected"

# Set path conversion conditionally
[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1

资源

• Git Bash 路径转换指南
• MSYS2 路径转换文档
• SqlPackage 文档
• Microsoft.Build.Sql SDK
• Git for Windows

故障排除

“Invalid parameter”错误

症状： SqlPackage 报告“Invalid parameter”或“Unknown action” 原因： Git Bash 将 /Action 转换为文件路径 解决方法： 使用 MSYS_NO_PATHCONV=1 或双斜杠 //Action

路径有效但提示“File not found”

症状： 尽管路径正确，却找不到 DACPAC 或项目文件 原因： 路径转换破坏了文件路径 解决方法： 将路径用引号括起来，并使用 MSYS_NO_PATHCONV=1

构建成功，但发布失败

症状： dotnet build 可以运行，但 sqlpackage 失败 原因： dotnet CLI 能正确处理路径，但 SqlPackage 使用 / 参数 解决方法： 仅对 SqlPackage 命令使用 MSYS_NO_PATHCONV=1

路径中包含空格导致错误

症状： 包含“Program Files”或其他空格的路径无法使用 原因： 未加引号的路径被拆分为多个参数 解决方法： 始终将路径用引号括起来：/SourceFile:"D:/Program Files/MyDB.dacpac"