Shiori Web 前端开发指南基于 Vue 3 Vite Bun 构建书签管理器界面【免费下载链接】shioriSimple bookmark manager built with Go项目地址: https://gitcode.com/gh_mirrors/sh/shiori本文围绕 shiori 仓库中 webapp/README.md 展开系统讲解新版 Web 前端的开发环境、依赖安装、本地热更新、类型检查、生产构建、单元测试与代码规范检查的完整流程。读完本文你将掌握用 Bun 驱动 Vue 3 Vite 技术栈开发、调试与产出 shiori 前端产物并理解该产物如何最终被嵌入 Go 二进制中随服务一起分发。webapp 在 shiori 中的定位shiori 是一个用 Go 编写的简单书签管理器Simple bookmark manager built with Go仓库同时维护着两套前端internal/view下的旧版模板页面以及webapp目录下的新版 Vue 3 单页应用。从 webapp/embed.go 可以看到前端构建产物通过 Go 的 embed 机制被打进二进制package webapp import ( embed ) //go:embed dist/index.html var Templates embed.FS //go:embed dist/assets dist/*.ico var Assets embed.FS也就是说webapp开发流程的终点是产出dist/index.html与dist/assets之后由 Go 侧统一嵌入并对外提供服务。因此本 README 中的每一条命令都直接关系到最后随 shiori 二进制一起发布的界面能否正确生成。推荐 IDE 环境VSCode VolarREADME 明确给出了编辑器建议使用 VSCode 并安装Volar扩展同时禁用 Vetur。原因在于 Vue 3 的 SFC单文件组件工具链与 Vue 2 时代不同类型检查由vue-tsc取代原生tsc承担编辑器中让 TypeScript 语言服务识别.vue文件类型信息的正是 Volar。从 webapp/package.json 的 devDependencies 中也能印证这一点项目同时依赖vue-tsc^2.2.12、typescript~5.8.3与vue/tsconfig^0.7.0。如果你在 IDE 中看到.vue导入报类型错误或没有补全首先应检查是否安装了 Volar 且 Vetur 已被禁用。项目依赖与技术栈全景先看 webapp/package.json 声明的依赖理解开发流程背后的技术选型运行时依赖dependencies依赖版本用途vue^3.5.22Vue 3 框架本体vue-router^4.5.1前端路由history 模式pinia^3.0.3状态管理登录态、标签数据vue-i18n^9.14.5国际化en/es/fr/de/ja 五种语言vueuse/core^13.9.0组合式工具函数集tailwindcss/vite^4.1.13Tailwind CSS 4 的 Vite 插件开发依赖devDependenciesvite^6.3.6、vitejs/plugin-vue、vite-plugin-vue-devtools、vitest^3.2.4、vue/test-utils、eslint^9.36.0、eslint-plugin-vue、prettier、npm-run-all2等覆盖构建、测试、lint 与格式化全链路。package.json 中的脚本定义如下scripts: { dev: vite, build: run-p type-check \build-only {}\ --, preview: vite preview, test:unit: vitest, build-only: vite build, type-check: vue-tsc --build, lint: eslint . --fix, format: prettier --write src/ }后续所有 README 命令都可以在本文件的 scripts 中找到一一对应关系。安装依赖bun install仓库在 webapp/bun.lock 与 webapp/bun.lockb 之外还保留了 webapp/package-lock.json说明项目同时兼容 Bun 与 npm 两类包管理器。README 以 Bun 为准如果你的环境没有安装 Bun也可以用npm install代替但建议遵循官方 README 使用 Bun以保证与 lockfile 的一致性。本地开发编译与热更新bun dev该命令实际执行vite启动带热更新Hot-Reload的开发服务器。Vite 的配置集中在 webapp/vite.config.tsexport default defineConfig({ plugins: [ vue(), vueDevTools(), tailwindcss(), ], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) }, }, css: { devSourcemap: true, }, })三个插件分别负责.vue单文件编译、Vue DevTools 调试面板和 Tailwind CSS 4 的按需扫描别名指向src目录这也是源码中随处可见/stores/auth、/client这类导入的原因devSourcemap开启 CSS 源码映射方便在浏览器中直接定位到 webapp/src/assets/main.css 等源文件。入口在 webapp/index.html它挂载#app并加载 webapp/src/main.ts。main.ts依次注册 Pinia、Vue Router 与 i18n 后挂载应用对应 webapp/src/App.vue 的根组件。类型检查与生产构建bun run build这一步与直接vite build不同它通过npm-run-all2的run-p并行执行type-check与build-only两个子任务——即先/同时做类型检查再产出生产包保证发布产物通过类型校验。type-check执行vue-tsc --build参照 webapp/tsconfig.app.json、webapp/tsconfig.json 等配置对整个src做类型检查这正是 README 强调“用 vue-tsc 替换 tsc”的实际落点build-only执行vite build将产物输出到dist/。构建完成后dist/index.html与dist/assets即被 webapp/embed.go 中声明的//go:embed指令收集。若想单独预览构建产物可运行bun run preview即vite preview它会以生产模式在本地起一个静态服务用于验收。单元测试Vitestbun test:unit对应脚本为vitest。测试配置在 webapp/vitest.config.ts它通过mergeConfig继承vite.config.ts的插件与别名配置并补充test: { environment: jsdom, exclude: [...configDefaults.exclude, e2e/**], root: fileURLToPath(new URL(./, import.meta.url)), }environment: jsdom在 Node 环境中模拟浏览器 DOM配合 webapp/src/assets/main.css 无关的纯逻辑与组件测试显式排除e2e/**将端到端测试隔离到仓库根目录的 e2e/Playwright Go 服务端测试体系之外避免单元与 E2E 混跑。ESLint 侧也通过vitest/eslint-plugin对src/**/__tests__/*目录启用了 Vitest 专属规则见 webapp/eslint.config.ts。代码规范ESLint 与 Prettierbun lint执行eslint . --fix。该项目使用 ESLint 9 的flat config写法webapp/eslint.config.tsexport default defineConfigWithVueTs( { name: app/files-to-lint, files: [**/*.{ts,mts,tsx,vue}], }, { name: app/files-to-ignore, ignores: [**/dist/**, **/dist-ssr/**, **/coverage/**], }, pluginVue.configs[flat/essential], vueTsConfigs.recommended, { ...pluginVitest.configs.recommended, files: [src/**/__tests__/*] }, skipFormatting, )要点lint 范围是全部 TS/MTS/TSX/Vue 文件但跳过构建产物目录vueTsConfigs.recommended让 Vue SFC 同时获得模板与脚本的类型感知skipFormatting意味着格式化交给 Prettier 负责即配套命令bun format对应prettier --write src/两者分工为ESLint 管代码质量未使用变量、类型问题、Vue 规范Prettier 管排版风格。前端架构速览开发时值得关注在开始写业务代码前快速熟悉 webapp/src 的目录划分能让你更高效地使用上面的工具链webapp/src/router/index.ts路由表定义/home、/login、/tags、/folders、/archive、/settings并在全局beforeEach守卫中结合 Pinia 的 auth store 做登录态校验未匹配路由统一重定向到/home。除/home、/login外各页面均使用动态import()做路由级代码分割webapp/src/stores/auth.ts以localStorage持久化 token 与过期时间封装login、logout、validateToken、refreshToken并通过X-Shiori-Response-Format: new请求头对接新的 API 响应格式注意开发时其 APIbasePath写死为http://localhost:8080webapp/src/stores/tags.ts标签的增删改查与本地状态同步webapp/src/utils/i18n.ts默认语言取自浏览器navigator.language优先级低于localStorage中的shiori-language语言包位于 webapp/src/localesen/es/fr/de/ja 五个 JSONwebapp/src/client由 OpenAPI Generator 根据 docs/swagger/swagger.json 自动生成的 API 客户端runtime.ts、apis/*、models/*其中的 webapp/src/client/runtime.ts 提供Configuration类用于注入 basePath、accessToken 与自定义 headerswebapp/src/views七个页面视图登录、主页、标签、文件夹、归档、设置、关于配合 webapp/src/components/layout 下的 AppLayout、Sidebar、TopBar、LanguageSelector 等布局组件使用。常见问题与注意事项改完代码要跑bun run build本地bun dev不会修改dist/只有构建后才能通过go:embed打进 Go 二进制。若修改了前端却看不到服务端界面变化多半是忘了重新构建。开发期 API 地址当前 webapp/src/stores/auth.ts 等 store 中basePath固定为http://localhost:8080本地联调时需保证 shiori 服务监听在 8080 端口部署到其他地址需按实际环境调整。编辑器类型提示不生效确认已安装 Volar 并禁用 Vetur同时建议直接打开webapp/目录而非仓库根目录以便 VSCode 正确加载根级 tsconfig。锁文件一致性项目同时存在 Bun 与 npm 两套 lockfile建议统一使用 README 推荐的bun install避免两套依赖树不一致导致 CI 与本地行为不同。测试隔离Vitest 配置已排除e2e/**单元测试与 e2e/ 的端到端测试Playwright Go 容器彼此独立跑bun test:unit前无需启动任何服务。综上webapp的开发闭环可以概括为bun install装依赖→bun dev迭代开发→bun test:unitbun lintbun format质量保障→bun run build产出dist/供 webapp/embed.go 嵌入。掌握这条链路你就能独立参与 shiori 新版界面的开发与构建发布。【免费下载链接】shioriSimple bookmark manager built with Go项目地址: https://gitcode.com/gh_mirrors/sh/shiori创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考