React项目SCSS相对URL配置异常：GitHub Pages部署后资源路径缺失仓库名

I’ve run into this exact issue before—when deploying to GitHub Pages, the absolute paths in your SCSS don’t account for the repository name that gets added to the URL structure. Here’s how to fix it:

Why This Happens #

When you use an absolute path like /assets/images/background/circle-1.svg in SCSS, it resolves to the root of the domain (https://username.github.io/) instead of your project’s subpath (https://username.github.io/repository-name/). Unlike JSX files (which are processed by Webpack with proper public path handling), SCSS url() references aren’t automatically adjusted unless you configure your build setup correctly.

Solutions #

1. Use Relative Paths in SCSS (Quick Fix) #

Instead of absolute paths, use relative paths from your SCSS file to the image assets. For example, if your SCSS file is located at public/assets/scss/common/styles.scss, the path to circle-1.svg would be:

.big-center-circle {
  background: url("../../images/background/circle-1.svg") no-repeat center top;
}

Count the ../ segments to navigate up from the SCSS file’s directory to the assets folder, then down to your image. This works locally and on GitHub Pages because it resolves relative to the compiled CSS file’s location.

2. Configure homepage in package.json (For Create React App) #

If you’re using Create React App, add the homepage field to your package.json pointing to your GitHub Pages URL:

{
  "homepage": "https://username.github.io/repository-name"
}

CRA automatically sets Webpack’s publicPath to match this value, which fixes asset paths across your project. However, you’ll still need to adjust your SCSS paths to be relative (not absolute) for this to take effect—absolute paths like /assets/... will still ignore the homepage setting in SCSS.

3. Custom Webpack Configuration (For Non-CRA Projects) #

If you have a custom Webpack setup, modify the output.publicPath in your Webpack config to include your repository name:

module.exports = {
  // ... other config
  output: {
    // ... other output settings
    publicPath: '/repository-name/'
  }
};

Additionally, you can define a global SCSS variable using sass-loader to inject the public path automatically. Add this to your Webpack module rules for SCSS:

module: {
  rules: [
    {
      test: /\.scss$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'sass-loader',
          options: {
            additionalData: `$public-path: "${process.env.PUBLIC_URL}";`
          }
        }
      ]
    }
  ]
}

Then use the variable in your SCSS:

.big-center-circle {
  background: url(#{$public-path}/assets/images/background/circle-1.svg) no-repeat center top;
}

Set the PUBLIC_URL environment variable to your repository path when building (e.g., PUBLIC_URL=/repository-name/ npm run build).

4. Verify React Router Setup #

While you mentioned JSX paths work, double-check that your BrowserRouter includes the basename prop to match your repository name:

import { BrowserRouter } from 'react-router-dom';

ReactDOM.render(
  <BrowserRouter basename="/repository-name">
    <App />
  </BrowserRouter>,
  document.getElementById('root')
);

This ensures your app’s routing works correctly on GitHub Pages, though it doesn’t directly fix SCSS asset paths—it’s just a good sanity check.

Final Notes #

Always test your build locally before deploying to GitHub Pages. Run npm run build and serve the build folder with a local server (like serve -s build) to confirm asset paths resolve correctly.

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