nsbp-cli 0.2.34 → 0.2.35

package/README.md

@@ -147,7 +147,7 @@ node ./bin/nsbp.js --help  # Test CLI locally
 
 - **Package Name**: `nsbp-cli`
 - **Bin Command**: `nsbp` (install globally and run `nsbp --help`)
-- **Version**: `0.2.34`
+- **Version**: `0.2.35`
 - **Dependencies**: chalk, commander, fs-extra, inquirer
 - **Package Manager**: Uses pnpm (also compatible with npm)
 - **Node Version**: >=16.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsbp-cli",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "description": "CLI tool for creating NSBP (Node React SSR by Webpack) projects",
   "main": "index.js",
   "homepage": "https://nsbp.erishen.cn/",

package/templates/basic/README.md

@@ -144,14 +144,24 @@ docker-compose exec app env | grep NODE_ENV
 
 ### 本地访问
 
-客户端渲染
+**服务端渲染**（默认，对 SEO 友好）
+```
 http://localhost:3001/
+```
 
-服务端渲染
-http://localhost:3001/?seo=1
+**客户端渲染**（禁用 SSR）
+```
+http://localhost:3001/?nsbp=0
+```
+
+**服务端渲染回退**（如果 SSR 失败，自动回退到客户端渲染）
+```
+http://localhost:3001/?nsbp=1&from=link
+```
 
-服务端渲染不成功，改为客户端渲染
-http://localhost:3001/?seo=1&from=link
+> **参数说明**：`nsbp` 参数控制渲染模式
+> - `nsbp=1` 或省略：服务端渲染（SSR，默认）
+> - `nsbp=0`：客户端渲染（CSR）
 
 ## Docker 部署
 

package/templates/basic/docs/DEVELOPMENT_GUIDE.md

@@ -25,10 +25,15 @@ pnpm run dev:build:start # 启动服务器
 
 ### 3. 访问应用
 
-- **客户端渲染**: http://localhost:3001/
-- **服务端渲染**: http://localhost:3001/?seo=1
+- **服务端渲染**（默认，SEO 友好）: http://localhost:3001/
+- **客户端渲染**（禁用 SSR）: http://localhost:3001/?nsbp=0
+- **服务端渲染回退**（SSR 失败时回退到 CSR）: http://localhost:3001/?nsbp=1&from=link
 - **BrowserSync**: http://localhost:3000/
 
+> **参数说明**：`nsbp` 参数控制渲染模式
+> - `nsbp=1` 或省略：服务端渲染（SSR，默认）
+> - `nsbp=0`：客户端渲染（CSR）
+
 ## 📝 开发工作流
 
 ### 提交代码

package/templates/basic/src/Routers.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import { loadData as homeLoadData } from '@services/home'
+import { loadData as photoLoadData } from '@services/photo'
 import loadable from '@loadable/component'
 
 const Loading = () => {
@@ -33,7 +34,7 @@ export default [
   {
     path: '/photo',
     element: <Photo />,
-    loadData: homeLoadData, // 使用相同的 loadData 来预取图片菜单
+    loadData: photoLoadData, // 使用 photo 的 loadData 来预取图片数据
     key: 'photo'
   }
 ]

package/templates/basic/src/client/index.tsx

@@ -9,13 +9,13 @@ import Theme from '@components/Theme'
 import { loadableReady } from '@loadable/component'
 
 const App = () => {
-  const [store, setStore] = useState(getStore())
-
-  useEffect(() => {
-    if (isSEO()) {
-      setStore(getStore(window?.context?.state))
+  // 优先使用服务端预取的状态初始化 store
+  const [store, setStore] = useState(() => {
+    if (isSEO() && window?.context?.state) {
+      return getStore(window.context.state)
     }
-  }, [])
+    return getStore()
+  })
 
   return (
     <Theme>

package/templates/basic/src/component/Layout.tsx

@@ -4,17 +4,17 @@ import Loading from './Loading'
 
 interface LayoutProps {
   children: React.ReactNode
-  query?: { seo?: string | number }
+  query?: { nsbp?: string | number }
 }
 
 const Layout = ({ children, query }: LayoutProps) => {
-  let seo: string | number | undefined
+  let nsbp: string | number | undefined
   if (query !== undefined && query !== null) {
-    seo = query.seo
+    nsbp = query.nsbp
   }
 
   const [pageLoad, setPageLoad] = useState(
-    seo !== undefined ? parseInt(String(seo), 10) : 0
+    nsbp !== undefined ? parseInt(String(nsbp), 10) : 0
   )
 
   useEffect(() => {

package/templates/basic/src/containers/Home.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useState } from 'react'
 import { Link } from 'react-router-dom'
 import Layout from '@components/Layout'
 import { Helmet } from 'react-helmet'
+import { isSEO, usePreserveNSBP } from '@/utils'
 import {
   GlobalStyle,
   PageWrapper,
@@ -66,20 +67,23 @@ interface PhotoMenuItem {
 const Home: React.FC = () => {
   const [menu, setMenu] = useState<PhotoMenuItem[]>([])
   const [loading, setLoading] = useState(true)
+  const { withNSBP } = usePreserveNSBP()
 
   useEffect(() => {
     if (typeof window === 'undefined') return
 
     setLoading(true)
+
+    // 检查是否为客户端渲染模式
+    const isClientMode = isSEO() === 0
+
     // 先检查服务端是否已预取了图片菜单数据
     const serverMenu = window?.context?.state?.photo?.menu || {}
     const serverMenuArray = Array.isArray(serverMenu) ? serverMenu : []
 
-    if (serverMenuArray.length > 0) {
-      setMenu(serverMenuArray)
-      setLoading(false)
-    } else {
-      // 如果服务端没有预取，则在客户端获取
+    // 客户端渲染模式下，始终发起新请求；服务端渲染模式下，如果有预取数据则使用预取数据
+    if (isClientMode || serverMenuArray.length === 0) {
+      // 客户端获取数据
       fetch('/getPhotoMenu')
         .then((res) => {
           if (!res.ok) throw new Error(`Status ${res.status}`)
@@ -93,6 +97,10 @@ const Home: React.FC = () => {
           setMenu([])
         })
         .finally(() => setLoading(false))
+    } else {
+      // 使用服务端预取的数据
+      setMenu(serverMenuArray)
+      setLoading(false)
     }
   }, [])
 
@@ -467,7 +475,10 @@ export const getPhotoMenu = (req: any, res: any) => {
             ) : menu.length > 0 ? (
               <PhotoGrid>
                 {menu.map((item) => (
-                  <Link key={item.name} to={`/photo?dic=${item.name}`}>
+                  <Link
+                    key={item.name}
+                    to={withNSBP(`/photo?dic=${item.name}`)}
+                  >
                     <PhotoCard>
                       <PhotoImageWrapper>
                         <PhotoImage

package/templates/basic/src/containers/Photo.tsx

@@ -1,4 +1,4 @@
-import React, { Fragment, useState, useEffect } from 'react'
+import React, { Fragment, useState, useEffect, useRef } from 'react'
 import { connect } from 'react-redux'
 import { Link, useLocation } from 'react-router-dom'
 import Header from '@components/Header'
@@ -6,10 +6,10 @@ import Layout from '@components/Layout'
 import { Helmet } from 'react-helmet'
 import { Container, Row } from '@styled/photo'
 import { motion } from 'framer-motion'
-import { isSEO, getLocationParams } from '@/utils'
+import { isSEO, getLocationParams, usePreserveNSBP } from '@/utils'
 import { useCurrentFlag } from '@utils/clientConfig'
 import _ from 'lodash'
-import { loadData } from '@services/photo'
+import { loadDataForContainer } from '@services/photo'
 
 const springSettings = { type: 'spring' as const, stiffness: 170, damping: 26 }
 const NEXT = 'show-next'
@@ -17,8 +17,11 @@ const NEXT = 'show-next'
 const Photo = ({ query, data, menu, getPhotoMenu }: any) => {
   const location = useLocation()
   let { from } = query
+  const { withNSBP } = usePreserveNSBP()
   const photos = Array.isArray(data) ? data : []
   const [currPhoto, setCurrPhoto] = useState(0)
+  // 使用 ref 来跟踪初始的 dic 值，用于区分首次加载和分类切换
+  const initialDicRef = useRef<string | null>(null)
 
   const [currPhotoData, setCurrPhotoData] = useState(photos[0] || [0, 0, ''])
 
@@ -70,23 +73,35 @@ const Photo = ({ query, data, menu, getPhotoMenu }: any) => {
   }
 
   useEffect(() => {
-    const currentDic = getLocationParams('dic')
+    const currentDic = getLocationParams('dic') || ''
+
+    // 初始化时记录初始 dic 值
+    if (initialDicRef.current === null) {
+      initialDicRef.current = currentDic
+    }
 
     const doGetPhotoMenu = () => {
       getPhotoMenu(currentDic)
     }
 
-    if (!isSEO()) {
+    // 判断是否需要加载数据：
+    // 1. 客户端渲染模式（isSEO() === 0）- 总是加载
+    // 2. 服务端渲染模式：
+    //    - 如果没有数据（hasNoData）- 需要加载
+    //    - 如果分类切换（isCategoryChanged）- 需要加载
+    const isClientMode = isSEO() === 0
+    const hasNoData = !data || data.length === 0
+    const isCategoryChanged = currentDic !== initialDicRef.current
+
+    // 客户端渲染模式：总是需要加载数据
+    // 服务端渲染模式：只有在没有数据或分类切换时才加载
+    if (isClientMode || hasNoData || isCategoryChanged) {
       doGetPhotoMenu()
-    } else {
-      if (from === 'link') {
-        doGetPhotoMenu()
-      }
     }
 
     // 重置到第一张
     setCurrPhoto(0)
-  }, [location?.search])
+  }, [location?.search, from])
 
   return (
     <Fragment>
@@ -101,7 +116,10 @@ const Photo = ({ query, data, menu, getPhotoMenu }: any) => {
           <Row>
             {_.map(menu, (item: any, index: number) => {
               return (
-                <Link key={`menu${index}`} to={`/photo?dic=${item.name}`}>
+                <Link
+                  key={`menu${index}`}
+                  to={withNSBP(`/photo?dic=${item.name}`)}
+                >
                   {item.name}
                 </Link>
               )
@@ -131,9 +149,9 @@ const Photo = ({ query, data, menu, getPhotoMenu }: any) => {
                   className="demo4-photo"
                   src={
                     photos[i][2]
-                      ? useCurrentFlag
+                      ? isSEO() === 1
                         ? `/images/${photos[i][2]}`
-                        : photos[i][2]
+                        : `/images/${photos[i][2]}`
                       : 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII='
                   }
                   initial={false}
@@ -167,7 +185,7 @@ const mapStateToProps = (state: any) => {
 
 const mapDispatchToProps = (dispatch: any) => ({
   getPhotoMenu: (dic: any) => {
-    dispatch(loadData(null, dic))
+    dispatch(loadDataForContainer(null, dic))
   }
 })
 

package/templates/basic/src/reducers/photo.ts

@@ -8,7 +8,7 @@ interface PhotoState {
 }
 
 export const photoReducer = (
-  state: PhotoState = { data: [[0, 0, '']], menu: {} },
+  state: PhotoState = { data: [], menu: {} },
   action: any
 ) => {
   const { type, data, menu } = action

package/templates/basic/src/server/index.ts

@@ -41,7 +41,6 @@ if (process.env.ENABLE_RATE_LIMIT === '1') {
     legacyHeaders: false // Disable the `X-RateLimit-*` headers
   })
   app.use('/api', limiter)
-  console.log('🛡️ Rate limiting enabled for /api routes')
 }
 
 // 4. Static file serving (disable dotfiles access)
@@ -79,15 +78,12 @@ app.get('/getPhotoMenu', (req, res) => {
 
 // Catch-all middleware for SSR
 app.use((req, res) => {
-  // console.log('req.url', req.url, req.headers)
   render(req, res)
 })
 
 const PORT = process.env.PORT || 3001
 app.listen(PORT, () => {
-  console.log(`Server listening on port ${PORT}`)
-  console.log(`🔒 Security headers enabled`)
   if (process.env.ENABLE_RATE_LIMIT === '1') {
-    console.log(`🚦 Rate limiting active`)
+    // Rate limiting active
   }
 })

package/templates/basic/src/server/photo.ts

@@ -85,6 +85,13 @@ export const getPhotoWH = (req: any, res: any) => {
       return res.status(403).json({ error: 'Access denied' })
     }
 
+    // 检查目录是否存在
+    if (!fs.existsSync(photoPath)) {
+      return res
+        .status(404)
+        .json({ error: 'Directory not found', details: photoPath })
+    }
+
     const getFileList = (dir: string, list: string[]) => {
       const arr = fs.readdirSync(dir)
       arr.forEach((item) => {

package/templates/basic/src/server/utils.tsx

@@ -19,10 +19,10 @@ export const render = (req: any, res: any) => {
   const matchRoutes: any = []
   const promises = []
 
-  let { seo } = query
+  let { nsbp } = query
 
-  if (seo !== undefined && seo !== '') {
-    seo = parseInt(seo, 10)
+  if (nsbp !== undefined && nsbp !== '') {
+    nsbp = parseInt(nsbp, 10)
   }
 
   routers.some((route) => {
@@ -33,7 +33,8 @@ export const render = (req: any, res: any) => {
     if (item?.loadData) {
       const promise = new Promise((resolve, reject) => {
         try {
-          store.dispatch(item?.loadData(resolve))
+          // 将 query 参数传递给 loadData，确保能正确预取数据
+          store.dispatch(item?.loadData(resolve, query))
         } catch (e) {
           reject()
         }

package/templates/basic/src/services/photo.ts

@@ -57,6 +57,14 @@ const getData = (callback: any, dic: any) => {
   }
 }
 
-export const loadData = (resolve: any = null, dic = '') => {
+// 用于路由预取数据的 loadData 函数
+export const loadData = (resolve: any = null, query: any = {}) => {
+  // 从 URL 查询参数中获取 dic
+  const { dic } = query
+  return getData(resolve, dic || '')
+}
+
+// 用于容器内部调用的 loadData 函数（保持向后兼容）
+export const loadDataForContainer = (resolve: any = null, dic = '') => {
   return getData(resolve, dic)
 }

package/templates/basic/src/store/index.ts

@@ -5,8 +5,7 @@ const combineReducer = combineReducers({ ...reducers })
 
 const getStore = (stateParam = {}) => {
   return configureStore({
-    reducer: (state: any, action: any) =>
-      combineReducer(state || stateParam, action),
+    reducer: combineReducer,
     preloadedState: stateParam || {},
     middleware: (getDefaultMiddleware) => getDefaultMiddleware()
   })

package/templates/basic/src/utils/index.ts

@@ -13,15 +13,73 @@ export const getLocationParams = (param: string) => {
 
 export const isSEO = () => {
   if (typeof window !== 'undefined') {
-    const seo = getLocationParams('seo')
-    if (seo !== '') {
-      return parseInt(seo, 10)
+    const nsbp = getLocationParams('nsbp')
+    if (nsbp !== '') {
+      return parseInt(nsbp, 10)
     }
-    return 0
+    return 1
   }
-  return 0
+  return 1
 }
 
+/**
+ * 获取当前的 nsbp 参数值
+ * @returns nsbp 参数值，如果没有则返回空字符串
+ */
+export const getNSBPParam = () => {
+  return getLocationParams('nsbp')
+}
+
+/**
+ * 在 URL 中保留/添加 nsbp 参数
+ * @param url - 原始 URL
+ * @param nsbpValue - 可选的 nsbp 值，如果不提供则使用当前 URL 中的值
+ * @returns 保留了 nsbp 参数的 URL
+ *
+ * @example
+ * appendNSBPParam('/photo?dic=test')
+ * // 如果当前 URL 是 /?nsbp=0，返回 '/photo?dic=test&nsbp=0'
+ *
+ * @example
+ * appendNSBPParam('/photo?dic=test', '0')
+ * // 返回 '/photo?dic=test&nsbp=0'
+ */
+export const appendNSBPParam = (url: string, nsbpValue?: string): string => {
+  // 如果指定了 nsbpValue 则使用它，否则使用当前 URL 中的值
+  const nsbp = nsbpValue !== undefined ? nsbpValue : getNSBPParam()
+
+  // 如果没有 nsbp 值，直接返回原 URL
+  if (!nsbp) {
+    return url
+  }
+
+  // 判断 URL 中是否已有查询参数
+  const separator = url.includes('?') ? '&' : '?'
+  return `${url}${separator}nsbp=${nsbp}`
+}
+
+/**
+ * 从 URL 中移除 nsbp 参数
+ * @param url - 原始 URL
+ * @returns 移除了 nsbp 参数的 URL
+ *
+ * @example
+ * removeNSBPParam('/photo?dic=test&nsbp=0')
+ * // 返回 '/photo?dic=test'
+ */
+export const removeNSBPParam = (url: string): string => {
+  const urlObj = new URL(
+    url,
+    typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+  )
+  urlObj.searchParams.delete('nsbp')
+  return urlObj.pathname + urlObj.search
+}
+
+/**
+ * 保留 handleLink 作为向后兼容的函数
+ * @deprecated 使用 appendNSBPParam 替代
+ */
 export const handleLink = (link: string) => {
   let result = link
 
@@ -31,7 +89,9 @@ export const handleLink = (link: string) => {
     } else {
       result += '?'
     }
-    result += 'seo=1'
+    result += 'nsbp=1'
   }
   return result
 }
+
+export { usePreserveNSBP } from './usePreserveNSBP'

package/templates/basic/src/utils/usePreserveNSBP.ts

@@ -0,0 +1,58 @@
+import { useMemo } from 'react'
+import { appendNSBPParam } from './index'
+
+/**
+ * React Hook 用于在路由跳转时保留 nsbp 参数
+ * @returns 包含三个方法的对象
+ *
+ * @example
+ * const { withNSBP, withNSBPValue, withoutNSBP } = usePreserveNSBP()
+ *
+ * // 保留当前的 nsbp 参数
+ * <Link to={withNSBP('/photo?dic=test')}>
+ *
+ * // 指定 nsbp 值
+ * <Link to={withNSBPValue('/photo?dic=test', '0')}>
+ *
+ * // 移除 nsbp 参数
+ * <Link to={withoutNSBP('/photo?dic=test&nsbp=0')}>
+ */
+export const usePreserveNSBP = () => {
+  return useMemo(
+    () => ({
+      /**
+       * 保留当前 URL 中的 nsbp 参数
+       * @param url - 原始 URL
+       * @returns 保留了 nsbp 参数的 URL
+       */
+      withNSBP: (url: string) => appendNSBPParam(url),
+
+      /**
+       * 指定 nsbp 参数值
+       * @param url - 原始 URL
+       * @param value - nsbp 参数值
+       * @returns 添加了指定 nsbp 值的 URL
+       */
+      withNSBPValue: (url: string, value: string) =>
+        appendNSBPParam(url, value),
+
+      /**
+       * 移除 URL 中的 nsbp 参数
+       * @param url - 原始 URL
+       * @returns 移除了 nsbp 参数的 URL
+       */
+      withoutNSBP: (url: string) => {
+        if (typeof window === 'undefined') return url
+
+        try {
+          const urlObj = new URL(url, window.location.origin)
+          urlObj.searchParams.delete('nsbp')
+          return urlObj.pathname + urlObj.search
+        } catch {
+          return url
+        }
+      }
+    }),
+    []
+  )
+}