fix: resolve asset URLs relative to document.baseURI (#122)

- Add resolveAssetUrl utility to handle relative paths for GitHub Pages deployment
- Update IconProvidersWrapper to resolve chain icon and token icon base URLs
- Fixes icons showing as /icons/... instead of /KeyApp/webapp/icons/... on gh-pages

Author: Gaubee

src/frontend-main.tsx

@@ -1,9 +1,10 @@
-import { StrictMode, lazy, Suspense, useCallback } from 'react'
+import { StrictMode, lazy, Suspense, useCallback, useMemo } from 'react'
 import { createRoot } from 'react-dom/client'
 import { QueryClientProvider } from '@tanstack/react-query'
 import { I18nextProvider } from 'react-i18next'
 import i18n from './i18n'
 import { queryClient } from './lib/query-client'
+import { resolveAssetUrl } from './lib/asset-url'
 import { ServiceProvider } from './services'
 import { MigrationProvider } from './contexts/MigrationContext'
 import { StackflowApp } from './StackflowApp'
@@ -32,15 +33,24 @@ const MockDevTools = __MOCK_MODE__
 
 function IconProvidersWrapper({ children }: { children: React.ReactNode }) {
   const configs = useChainConfigs()
-  
+
+  // 预处理配置：解析所有相对路径为完整 URL
+  const resolvedConfigs = useMemo(() => {
+    return configs.map((config) => ({
+      ...config,
+      icon: config.icon ? resolveAssetUrl(config.icon) : undefined,
+      tokenIconBase: config.tokenIconBase?.map(resolveAssetUrl),
+    }))
+  }, [configs])
+
   const getIconUrl = useCallback(
-    (chainId: string) => configs.find((c) => c.id === chainId)?.icon,
-    [configs],
+    (chainId: string) => resolvedConfigs.find((c) => c.id === chainId)?.icon,
+    [resolvedConfigs],
   )
 
   const getTokenIconBases = useCallback(
-    (chainId: string) => configs.find((c) => c.id === chainId)?.tokenIconBase ?? [],
-    [configs],
+    (chainId: string) => resolvedConfigs.find((c) => c.id === chainId)?.tokenIconBase ?? [],
+    [resolvedConfigs],
   )
 
   return (

src/lib/asset-url.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { resolveAssetUrl } from './asset-url'
+
+describe('resolveAssetUrl', () => {
+  const originalBaseURI = document.baseURI
+
+  beforeEach(() => {
+    // Mock document.baseURI
+    Object.defineProperty(document, 'baseURI', {
+      value: 'https://example.com/app/',
+      configurable: true,
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(document, 'baseURI', {
+      value: originalBaseURI,
+      configurable: true,
+    })
+  })
+
+  it('resolves absolute path starting with /', () => {
+    expect(resolveAssetUrl('/icons/eth.svg')).toBe('https://example.com/app/icons/eth.svg')
+  })
+
+  it('resolves relative path starting with ./', () => {
+    expect(resolveAssetUrl('./icons/eth.svg')).toBe('https://example.com/app/icons/eth.svg')
+  })
+
+  it('returns http URLs unchanged', () => {
+    expect(resolveAssetUrl('http://cdn.example.com/icon.svg')).toBe('http://cdn.example.com/icon.svg')
+  })
+
+  it('returns https URLs unchanged', () => {
+    expect(resolveAssetUrl('https://cdn.example.com/icon.svg')).toBe('https://cdn.example.com/icon.svg')
+  })
+
+  it('returns other strings unchanged', () => {
+    expect(resolveAssetUrl('icon.svg')).toBe('icon.svg')
+  })
+
+  describe('with GitHub Pages style baseURI', () => {
+    beforeEach(() => {
+      Object.defineProperty(document, 'baseURI', {
+        value: 'https://bioforestchain.github.io/KeyApp/webapp/',
+        configurable: true,
+      })
+    })
+
+    it('correctly resolves /icons path', () => {
+      expect(resolveAssetUrl('/icons/ethereum/chain.svg')).toBe(
+        'https://bioforestchain.github.io/KeyApp/webapp/icons/ethereum/chain.svg'
+      )
+    })
+
+    it('correctly resolves /icons/tokens path', () => {
+      expect(resolveAssetUrl('/icons/bfmeta/tokens')).toBe(
+        'https://bioforestchain.github.io/KeyApp/webapp/icons/bfmeta/tokens'
+      )
+    })
+  })
+
+  describe('with localhost baseURI', () => {
+    beforeEach(() => {
+      Object.defineProperty(document, 'baseURI', {
+        value: 'http://localhost:5173/',
+        configurable: true,
+      })
+    })
+
+    it('correctly resolves /icons path', () => {
+      expect(resolveAssetUrl('/icons/ethereum/chain.svg')).toBe(
+        'http://localhost:5173/icons/ethereum/chain.svg'
+      )
+    })
+  })
+})

src/lib/asset-url.ts

@@ -0,0 +1,37 @@
+/**
+ * 资源 URL 解析工具
+ *
+ * 解决部署到子路径（如 GitHub Pages）时，以 `/` 开头的相对路径无法正确解析的问题。
+ * 使用 document.baseURI 作为基础 URL 来解析路径。
+ */
+
+/**
+ * 解析资源 URL
+ *
+ * - 以 `/` 开头的路径：基于 document.baseURI 解析
+ * - 以 `./` 开头的路径：基于 document.baseURI 解析
+ * - 已经是完整 URL（http/https）：直接返回
+ * - 其他情况：直接返回
+ *
+ * @example
+ * // 假设 document.baseURI = 'https://example.com/app/'
+ * resolveAssetUrl('/icons/eth.svg')       // => 'https://example.com/app/icons/eth.svg'
+ * resolveAssetUrl('./icons/eth.svg')      // => 'https://example.com/app/icons/eth.svg'
+ * resolveAssetUrl('https://cdn.com/a.svg') // => 'https://cdn.com/a.svg'
+ */
+export function resolveAssetUrl(path: string): string {
+  // 已经是完整 URL
+  if (path.startsWith('http://') || path.startsWith('https://')) {
+    return path
+  }
+
+  // 以 `/` 或 `./` 开头的相对路径，基于 baseURI 解析
+  if (path.startsWith('/') || path.startsWith('./')) {
+    // 去掉开头的 `/` 或 `./`
+    const relativePath = path.startsWith('/') ? path.slice(1) : path.slice(2)
+    return new URL(relativePath, document.baseURI).href
+  }
+
+  // 其他情况直接返回
+  return path
+}